1 @set gprconfig GPRconfig
3 @c ------ projects.texi
4 @c Copyright (C) 2002-2014, 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
9 @c ---------------------------------------------
10 @node GNAT Project Manager
11 @chapter GNAT Project Manager
12 @c ---------------------------------------------
17 * Building With Projects::
18 * Organizing Projects into Subsystems::
19 * Scenarios in Projects::
22 * Aggregate Projects::
23 * Aggregate Library Projects::
24 * Project File Reference::
27 @c ---------------------------------------------
30 @c ---------------------------------------------
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:
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^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 in Projects}).
52 @item Automatically build libraries as part of the build process
53 (@pxref{Library Projects}).
58 Project files are written in a syntax close to that of Ada, using familiar
59 notions such as packages, context clauses, declarations, default values,
60 assignments, and inheritance (@pxref{Project File Reference}).
62 Project files can be built hierarchically from other project files, simplifying
63 complex system integration and project reuse (@pxref{Organizing Projects into
67 @item One project can import other projects containing needed source files.
68 More generally, the Project Manager lets you structure large development
69 efforts into hierarchical subsystems, where build decisions are delegated
70 to the subsystem level, and thus different compilation environments
71 (^switch^switch^ settings) used for different subsystems.
72 @item You can organize GNAT projects in a hierarchy: a child project
73 can extend a parent project, inheriting the parent's source files and
74 optionally overriding any of them with alternative versions
75 (@pxref{Project Extension}).
80 Several tools support project files, generally in addition to specifying
81 the information on the command line itself). They share common switches
82 to control the loading of the project (in particular
83 @option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
84 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).
86 The Project Manager supports a wide range of development strategies,
87 for systems of all sizes. Here are some typical practices that are
91 @item Using a common set of source files and generating object files in different
92 directories via different ^switch^switch^ settings. It can be used for instance, for
93 generating separate sets of object files for debugging and for production.
94 @item Using a mostly-shared set of source files with different versions of
95 some units or subunits. It can be used for instance, for grouping and hiding
99 all OS dependencies in a small number of implementation units.
101 Project files can be used to achieve some of the effects of a source
102 versioning system (for example, defining separate projects for
103 the different sets of sources that comprise different releases) but the
104 Project Manager is independent of any source configuration management tool
105 that might be used by the developers.
107 The various sections below introduce the different concepts related to
108 projects. Each section starts with examples and use cases, and then goes into
109 the details of related project file capabilities.
111 @c ---------------------------------------------
112 @node Building With Projects
113 @section Building With Projects
114 @c ---------------------------------------------
117 In its simplest form, a unique project is used to build a single executable.
118 This section concentrates on such a simple setup. Later sections will extend
119 this basic model to more complex setups.
121 The following concepts are the foundation of project files, and will be further
122 detailed later in this documentation. They are summarized here as a reference.
125 @item @b{Project file}:
126 A text file using an Ada-like syntax, generally using the @file{.gpr}
127 extension. It defines build-related characteristics of an application.
128 The characteristics include the list of sources, the location of those
129 sources, the location for the generated object files, the name of
130 the main program, and the options for the various tools involved in the
133 @item @b{Project attribute}:
134 A specific project characteristic is defined by an attribute clause. Its
135 value is a string or a sequence of strings. All settings in a project
136 are defined through a list of predefined attributes with precise
137 semantics. @xref{Attributes}.
139 @item @b{Package in a project}:
140 Global attributes are defined at the top level of a project.
141 Attributes affecting specific tools are grouped in a
142 package whose name is related to tool's function. The most common
143 packages are @code{Builder}, @code{Compiler}, @code{Binder},
144 and @code{Linker}. @xref{Packages}.
146 @item @b{Project variables}:
147 In addition to attributes, a project can use variables to store intermediate
148 values and avoid duplication in complex expressions. It can be initialized
149 with a value coming from the environment.
150 A frequent use of variables is to define scenarios.
151 @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.
153 @item @b{Source files} and @b{source directories}:
154 A source file is associated with a language through a naming convention. For
155 instance, @code{foo.c} is typically the name of a C source file;
156 @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a
157 file containing an Ada spec. A compilation unit is often composed of a main
158 source file and potentially several auxiliary ones, such as header files in C.
159 The naming conventions can be user defined @xref{Naming Schemes}, and will
160 drive the builder to call the appropriate compiler for the given source file.
161 Source files are searched for in the source directories associated with the
162 project through the @b{Source_Dirs} attribute. By default, all the files (in
163 these source directories) following the naming conventions associated with the
164 declared languages are considered to be part of the project. It is also
165 possible to limit the list of source files using the @b{Source_Files} or
166 @b{Source_List_File} attributes. Note that those last two attributes only
167 accept basenames with no directory information.
169 @item @b{Object files} and @b{object directory}:
170 An object file is an intermediate file produced by the compiler from a
171 compilation unit. It is used by post-compilation tools to produce
172 final executables or libraries. Object files produced in the context of
173 a given project are stored in a single directory that can be specified by the
174 @b{Object_Dir} attribute. In order to store objects in
175 two or more object directories, the system must be split into
176 distinct subsystems with their own project file.
181 The following subsections introduce gradually all the attributes of interest
182 for simple build needs. Here is the simple setup that will be used in the
185 The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in
186 the @file{common/} directory. The file @file{proc.adb} contains an Ada main
187 subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile
188 these source files with the ^switch^switch^
189 @option{^-O2^-O2^}, and put the resulting files in
190 the directory @file{obj/}.
200 ^common/release/^[COMMON.RELEASE]^
201 proc.ali, proc.o pack.ali, pack.o
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.
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:
216 @b{project} Build @b{is}
221 * Source Files and Directories::
222 * Duplicate Sources in Projects::
223 * Object and Exec Directory::
225 * Tools Options in Project Files::
226 * Compiling with Project Files::
227 * Executable File Names::
228 * Avoid Duplication With Variables::
231 * Distributed support::
234 @c ---------------------------------------------
235 @node Source Files and Directories
236 @subsection Source Files and Directories
237 @c ---------------------------------------------
240 When you create a new project, the first thing to describe is how to find the
241 corresponding source files. This is the only settings that are needed by all
242 the tools that will use this project (builder, compiler, binder and linker for
243 the compilation, IDEs to edit the source files,@dots{}).
245 @cindex Source directories
246 First step is to declare the source directories, which are the directories
247 to be searched to find source files. In the case of the example,
248 the @file{common} directory is the only source directory.
250 @cindex @code{Source_Dirs}
251 There are several ways of defining source directories:
254 @item When the attribute @b{Source_Dirs} is not used, a project contains a
255 single source directory which is the one where the project file itself
256 resides. In our example, if @file{build.gpr} is placed in the @file{common}
257 directory, the project has the needed implicit source directory.
259 @item The attribute @b{Source_Dirs} can be set to a list of path names, one
260 for each of the source directories. Such paths can either be absolute
261 names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the
262 directory in which the project file resides (for instance "." if
263 @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
264 Each of the source directories must exist and be readable.
267 The syntax for directories is platform specific. For portability, however,
268 the project manager will always properly translate UNIX-like path names to
269 the native format of specific platform. For instance, when the same project
270 file is to be used both on Unix and Windows, "/" should be used as the
271 directory separator rather than "\".
273 @item The attribute @b{Source_Dirs} can automatically include subdirectories
274 using a special syntax inspired by some UNIX shells. If any of the path in
275 the list ends with @emph{"**"}, then that path and all its subdirectories
276 (recursively) are included in the list of source directories. For instance,
277 @file{**} and @file{./**} represent the complete directory tree rooted at ".".
278 @cindex Source directories, recursive
280 @cindex @code{Excluded_Source_Dirs}
281 When using that construct, it can sometimes be convenient to also use the
282 attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry
283 specifies a directory whose immediate content, not including subdirs, is to
284 be excluded. It is also possible to exclude a complete directory subtree
285 using the "**" notation.
287 @cindex @code{Ignore_Source_Sub_Dirs}
288 It is often desirable to remove, from the source directories, directory
289 subtrees rooted at some subdirectories. An example is the subdirectories
290 created by a Version Control System such as Subversion that creates directory
291 subtrees rooted at subdirectories ".svn". To do that, attribute
292 @b{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple
293 file names for the roots of these undesirable directory subtrees.
296 @b{for} Source_Dirs @b{use} ("./**");
297 @b{for} Ignore_Source_Sub_Dirs @b{use} (".svn");
303 When applied to the simple example, and because we generally prefer to have
304 the project file at the toplevel directory rather than mixed with the sources,
305 we will create the following file
309 @b{project} Build @b{is}
310 @b{for} Source_Dirs @b{use} ("common"); -- <<<<
315 Once source directories have been specified, one may need to indicate
316 source files of interest. By default, all source files present in the source
317 directories are considered by the project manager. When this is not desired,
318 it is possible to specify the list of sources to consider explicitly.
319 In such a case, only source file base names are indicated and not
320 their absolute or relative path names. The project manager is in charge of
321 locating the specified source files in the specified source directories.
324 @item By default, the project manager search for all source files of all
325 specified languages in all the source directories.
327 Since the project manager was initially developed for Ada environments, the
328 default language is usually Ada and the above project file is complete: it
329 defines without ambiguity the sources composing the project: that is to say,
330 all the sources in subdirectory "common" for the default language (Ada) using
331 the default naming convention.
333 @cindex @code{Languages}
334 However, when compiling a multi-language application, or a pure C
335 application, the project manager must be told which languages are of
336 interest, which is done by setting the @b{Languages} attribute to a list of
337 strings, each of which is the name of a language. Tools like
338 @command{gnatmake} only know about Ada, while other tools like
339 @command{gprbuild} know about many more languages such as C, C++, Fortran,
340 assembly and others can be added dynamically.
342 @cindex Naming scheme
343 Even when using only Ada, the default naming might not be suitable. Indeed,
344 how does the project manager recognizes an "Ada file" from any other
345 file? Project files can describe the naming scheme used for source files,
346 and override the default (@pxref{Naming Schemes}). The default is the
347 standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
348 specs), which is what is used in our example, explaining why no naming scheme
349 is explicitly specified.
350 @xref{Naming Schemes}.
352 @item @code{Source_Files}
353 @cindex @code{Source_Files}
354 In some cases, source directories might contain files that should not be
355 included in a project. One can specify the explicit list of file names to
356 be considered through the @b{Source_Files} attribute.
357 When this attribute is defined, instead of looking at every file in the
358 source directories, the project manager takes only those names into
359 consideration reports errors if they cannot be found in the source
360 directories or does not correspond to the naming scheme.
362 @item For various reasons, it is sometimes useful to have a project with no
363 sources (most of the time because the attributes defined in the project
364 file will be reused in other projects, as explained in
365 @pxref{Organizing Projects into Subsystems}. To do this, the attribute
366 @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
367 @emph{Source_Dirs} can be set to the empty list, with the same
370 @item @code{Source_List_File}
371 @cindex @code{Source_List_File}
372 If there is a great number of files, it might be more convenient to use
373 the attribute @b{Source_List_File}, which specifies the full path of a file.
374 This file must contain a list of source file names (one per line, no
375 directory information) that are searched as if they had been defined
376 through @emph{Source_Files}. Such a file can easily be created through
379 A warning is issued if both attributes @code{Source_Files} and
380 @code{Source_List_File} are given explicit values. In this case, the
381 attribute @code{Source_Files} prevails.
383 @item @code{Excluded_Source_Files}
384 @cindex @code{Excluded_Source_Files}
385 @cindex @code{Locally_Removed_Files}
386 @cindex @code{Excluded_Source_List_File}
387 Specifying an explicit list of files is not always convenient.It might be
388 more convenient to use the default search rules with specific exceptions.
389 This can be done thanks to the attribute @b{Excluded_Source_Files}
390 (or its synonym @b{Locally_Removed_Files}).
391 Its value is the list of file names that should not be taken into account.
392 This attribute is often used when extending a project,
393 @xref{Project Extension}. A similar attribute
394 @b{Excluded_Source_List_File} plays the same
395 role but takes the name of file containing file names similarly to
396 @code{Source_List_File}.
401 In most simple cases, such as the above example, the default source file search
402 behavior provides the expected result, and we do not need to add anything after
403 setting @code{Source_Dirs}. The project manager automatically finds
404 @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the
407 Note that by default a warning is issued when a project has no sources attached
408 to it and this is not explicitly indicated in the project file.
410 @c ---------------------------------------------
411 @node Duplicate Sources in Projects
412 @subsection Duplicate Sources in Projects
413 @c ---------------------------------------------
416 If the order of the source directories is known statically, that is if
417 @code{"/**"} is not used in the string list @code{Source_Dirs}, then there may
418 be several files with the same source file name sitting in different
419 directories of the project. In this case, only the file in the first directory
420 is considered as a source of the project and the others are hidden. If
421 @code{"/**"} is used in the string list @code{Source_Dirs}, it is an error
422 to have several files with the same source file name in the same directory
423 @code{"/**"} subtree, since there would be an ambiguity as to which one should
424 be used. However, two files with the same source file name may exist in two
425 single directories or directory subtrees. In this case, the one in the first
426 directory or directory subtree is a source of the project.
428 If there are two sources in different directories of the same @code{"/**"}
429 subtree, one way to resolve the problem is to exclude the directory of the
430 file that should not be used as a source of the project.
432 @c ---------------------------------------------
433 @node Object and Exec Directory
434 @subsection Object and Exec Directory
435 @c ---------------------------------------------
438 The next step when writing a project is to indicate where the compiler should
439 put the object files. In fact, the compiler and other tools might create
440 several different kind of files (for GNAT, there is the object file and the ALI
441 file for instance). One of the important concepts in projects is that most
442 tools may consider source directories as read-only and do not attempt to create
443 new or temporary files there. Instead, all files are created in the object
444 directory. It is of course not true for project-aware IDEs, whose purpose it is
445 to create the source files.
447 @cindex @code{Object_Dir}
448 The object directory is specified through the @b{Object_Dir} attribute.
449 Its value is the path to the object directory, either absolute or
450 relative to the directory containing the project file. This
451 directory must already exist and be readable and writable, although
452 some tools have a switch to create the directory if needed (See
453 the switch @code{^-p^/CREATE_MISSING_DIRS^} for @command{gnatmake}
454 and @command{gprbuild}).
456 If the attribute @code{Object_Dir} is not specified, it defaults to
457 the project directory, that is the directory containing the project file.
459 For our example, we can specify the object dir in this way:
462 @b{project} Build @b{is}
463 @b{for} Source_Dirs @b{use} ("common");
464 @b{for} Object_Dir @b{use} "obj"; -- <<<<
469 As mentioned earlier, there is a single object directory per project. As a
470 result, if you have an existing system where the object files are spread in
471 several directories, you can either move all of them into the same directory if
472 you want to build it with a single project file, or study the section on
473 subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
474 separate object directory can be associated with one of the subsystem
475 constituting the application.
477 When the @command{linker} is called, it usually creates an executable. By
478 default, this executable is placed in the object directory of the project. It
479 might be convenient to store it in its own directory.
481 @cindex @code{Exec_Dir}
482 This can be done through the @code{Exec_Dir} attribute, which, like
483 @emph{Object_Dir} contains a single absolute or relative path and must point to
484 an existing and writable directory, unless you ask the tool to create it on
485 your behalf. When not specified, It defaults to the object directory and
486 therefore to the project file's directory if neither @emph{Object_Dir} nor
487 @emph{Exec_Dir} was specified.
489 In the case of the example, let's place the executable in the root
490 of the hierarchy, ie the same directory as @file{build.gpr}. Hence
491 the project file is now
494 @b{project} Build @b{is}
495 @b{for} Source_Dirs @b{use} ("common");
496 @b{for} Object_Dir @b{use} "obj";
497 @b{for} Exec_Dir @b{use} "."; -- <<<<
501 @c ---------------------------------------------
502 @node Main Subprograms
503 @subsection Main Subprograms
504 @c ---------------------------------------------
507 In the previous section, executables were mentioned. The project manager needs
508 to be taught what they are. In a project file, an executable is indicated by
509 pointing to source file of the main subprogram. In C this is the file that
510 contains the @code{main} function, and in Ada the file that contains the main
513 There can be any number of such main files within a given project, and thus
514 several executables can be built in the context of a single project file. Of
515 course, one given executable might not (and in fact will not) need all the
516 source files referenced by the project. As opposed to other build environments
517 such as @command{makefile}, one does not need to specify the list of
518 dependencies of each executable, the project-aware builders knows enough of the
519 semantics of the languages to build ands link only the necessary elements.
522 The list of main files is specified via the @b{Main} attribute. It contains
523 a list of file names (no directories). If a project defines this
524 attribute, it is not necessary to identify main files on the
525 command line when invoking a builder, and editors like
526 @command{GPS} will be able to create extra menus to spawn or debug the
527 corresponding executables.
530 @b{project} Build @b{is}
531 @b{for} Source_Dirs @b{use} ("common");
532 @b{for} Object_Dir @b{use} "obj";
533 @b{for} Exec_Dir @b{use} ".";
534 @b{for} Main @b{use} ("proc.adb"); -- <<<<
539 If this attribute is defined in the project, then spawning the builder
540 with a command such as
543 gnatmake ^-Pbuild^/PROJECT_FILE=build^
547 automatically builds all the executables corresponding to the files
548 listed in the @emph{Main} attribute. It is possible to specify one
549 or more executables on the command line to build a subset of them.
551 @c ---------------------------------------------
552 @node Tools Options in Project Files
553 @subsection Tools Options in Project Files
554 @c ---------------------------------------------
557 We now have a project file that fully describes our environment, and can be
558 used to build the application with a simple @command{gnatmake} command as seen
559 in the previous section. In fact, the empty project we showed immediately at
560 the beginning (with no attribute at all) could already fulfill that need if it
561 was put in the @file{common} directory.
563 Of course, we always want more control. This section will show you how to
564 specify the compilation switches that the various tools involved in the
565 building of the executable should use.
567 @cindex command line length
568 Since source names and locations are described into the project file, it is not
569 necessary to use switches on the command line for this purpose (switches such
570 as -I for gcc). This removes a major source of command line length overflow.
571 Clearly, the builders will have to communicate this information one way or
572 another to the underlying compilers and tools they call but they usually use
573 response files for this and thus should not be subject to command line
576 Several tools are participating to the creation of an executable: the compiler
577 produces object files from the source files; the binder (in the Ada case)
578 creates an source file that takes care, among other things, of elaboration
579 issues and global variables initialization; and the linker gathers everything
580 into a single executable that users can execute. All these tools are known by
581 the project manager and will be called with user defined switches from the
582 project files. However, we need to introduce a new project file concept to
583 express which switches to be used for any of the tools involved in the build.
585 @cindex project file packages
586 A project file is subdivided into zero or more @b{packages}, each of which
587 contains the attributes specific to one tool (or one set of tools). Project
588 files use an Ada-like syntax for packages. Package names permitted in project
589 files are restricted to a predefined set (@pxref{Packages}), and the contents
590 of packages are limited to a small set of constructs and attributes
591 (@pxref{Attributes}).
593 Our example project file can be extended with the following empty packages. At
594 this stage, they could all be omitted since they are empty, but they show which
595 packages would be involved in the build process.
598 @b{project} Build @b{is}
599 @b{for} Source_Dirs @b{use} ("common");
600 @b{for} Object_Dir @b{use} "obj";
601 @b{for} Exec_Dir @b{use} ".";
602 @b{for} Main @b{use} ("proc.adb");
604 @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
607 @b{package} Compiler @b{is} --<<< for the compiler
610 @b{package} Binder @b{is} --<<< for the binder
613 @b{package} Linker @b{is} --<<< for the linker
619 Let's first examine the compiler switches. As stated in the initial description
620 of the example, we want to compile all files with @option{^-O2^-O2^}. This is a
621 compiler switch, although it is usual, on the command line, to pass it to the
622 builder which then passes it to the compiler. It is recommended to use directly
623 the right package, which will make the setup easier to understand for other
626 Several attributes can be used to specify the ^switches^switches^:
629 @item @b{Default_Switches}:
630 @cindex @code{Default_Switches}
631 This is the first mention in this manual of an @b{indexed attribute}. When
632 this attribute is defined, one must supply an @emph{index} in the form of a
634 In the case of @emph{Default_Switches}, the index is the name of the
635 language to which the switches apply (since a different compiler will
636 likely be used for each language, and each compiler has its own set of
637 switches). The value of the attribute is a list of switches.
639 In this example, we want to compile all Ada source files with the ^switch^switch^
640 @option{^-O2^-O2^}, and the resulting project file is as follows
641 (only the @code{Compiler} package is shown):
644 @b{package} Compiler @b{is}
645 @b{for} Default_Switches ("Ada") @b{use} ("^-O2^-O2^");
649 @item @b{^Switches^Switches^}:
650 @cindex @code{^Switches^Switches^}
651 in some cases, we might want to use specific ^switches^switches^
652 for one or more files. For instance, compiling @file{proc.adb} might not be
653 possible at high level of optimization because of a compiler issue.
654 In such a case, the @emph{^Switches^Switches^}
655 attribute (indexed on the file name) can be used and will override the
656 switches defined by @emph{Default_Switches}. Our project file would
661 for Default_Switches ("Ada")
663 for ^Switches^Switches^ ("proc.adb")
669 @code{^Switches^Switches^} may take a pattern as an index, such as in:
673 for Default_Switches ("Ada")
675 for ^Switches^Switches^ ("pkg*")
681 Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with ^-O0^-O0^,
685 @code{^Switches^Switches^} can also be given a language name as index instead of a file
686 name in which case it has the same semantics as @emph{Default_Switches}.
687 However, indexes with wild cards are never valid for language name.
689 @item @b{Local_Configuration_Pragmas}:
690 @cindex @code{Local_Configuration_Pragmas}
691 this attribute may specify the path
692 of a file containing configuration pragmas for use by the Ada compiler,
693 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
694 used for all the sources of the project.
698 The switches for the other tools are defined in a similar manner through the
699 @b{Default_Switches} and @b{^Switches^Switches^} attributes, respectively in the
700 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
701 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
702 package (for linking executables).
704 @c ---------------------------------------------
705 @node Compiling with Project Files
706 @subsection Compiling with Project Files
707 @c ---------------------------------------------
710 Now that our project files are written, let's build our executable.
711 Here is the command we would use from the command line:
714 gnatmake ^-Pbuild^/PROJECT_FILE=build^
718 This will automatically build the executables specified through the
719 @emph{Main} attribute: for each, it will compile or recompile the
720 sources for which the object file does not exist or is not up-to-date; it
721 will then run the binder; and finally run the linker to create the
724 @command{gnatmake} only knows how to handle Ada files. By using
725 @command{gprbuild} as a builder, you could automatically manage C files the
726 same way: create the file @file{utils.c} in the @file{common} directory,
727 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
730 gprbuild ^-Pbuild^/PROJECT_FILE=build^
734 Gprbuild knows how to recompile the C files and will
735 recompile them only if one of their dependencies has changed. No direct
736 indication on how to build the various elements is given in the
737 project file, which describes the project properties rather than a
738 set of actions to be executed. Here is the invocation of
739 @command{gprbuild} when building a multi-language program:
752 Notice the three steps described earlier:
755 @item The first three gcc commands correspond to the compilation phase.
756 @item The gprbind command corresponds to the post-compilation phase.
757 @item The last gcc command corresponds to the final link.
762 @cindex @option{-v} option (for GPRbuild)
763 The default output of GPRbuild's execution is kept reasonably simple and easy
764 to understand. In particular, some of the less frequently used commands are not
765 shown, and some parameters are abbreviated. So it is not possible to rerun the
766 effect of the @command{gprbuild} command by cut-and-pasting its output.
767 GPRbuild's option @code{-v} provides a much more verbose output which includes,
768 among other information, more complete compilation, post-compilation and link
771 @c ---------------------------------------------
772 @node Executable File Names
773 @subsection Executable File Names
774 @c ---------------------------------------------
777 @cindex @code{Executable}
778 By default, the executable name corresponding to a main file is
779 computed from the main source file name. Through the attribute
780 @b{Builder.Executable}, it is possible to change this default.
782 For instance, instead of building @command{proc} (or @command{proc.exe}
783 on Windows), we could configure our project file to build "proc1"
784 (resp proc1.exe) with the following addition:
786 @smallexample @c projectfile
788 ... -- same as before
790 for Executable ("proc.adb") use "proc1";
796 @cindex @code{Executable_Suffix}
797 Attribute @b{Executable_Suffix}, when specified, may change the suffix
798 of the executable files, when no attribute @code{Executable} applies:
799 its value replace the platform-specific executable suffix.
800 The default executable suffix is empty on UNIX and ".exe" on Windows.
802 It is also possible to change the name of the produced executable by using the
803 command line switch @option{-o}. When several mains are defined in the project,
804 it is not possible to use the @option{-o} switch and the only way to change the
805 names of the executable is provided by Attributes @code{Executable} and
806 @code{Executable_Suffix}.
808 @c ---------------------------------------------
809 @node Avoid Duplication With Variables
810 @subsection Avoid Duplication With Variables
811 @c ---------------------------------------------
814 To illustrate some other project capabilities, here is a slightly more complex
815 project using similar sources and a main program in C:
817 @smallexample @c projectfile
819 for Languages use ("Ada", "C");
820 for Source_Dirs use ("common");
821 for Object_Dir use "obj";
822 for Main use ("main.c");
824 C_Switches := ("-pedantic");
825 for Default_Switches ("C") use C_Switches;
826 for Default_Switches ("Ada") use ("^-gnaty^-gnaty^");
827 for ^Switches^Switches^ ("main.c") use C_Switches & ("-g");
833 This project has many similarities with the previous one.
834 As expected, its @code{Main} attribute now refers to a C source.
835 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
836 executable will be put in the directory @file{obj}.
838 The most noticeable difference is the use of a variable in the
839 @emph{Compiler} package to store settings used in several attributes.
840 This avoids text duplication, and eases maintenance (a single place to
841 modify if we want to add new switches for C files). We will revisit
842 the use of variables in the context of scenarios (@pxref{Scenarios in
845 In this example, we see how the file @file{main.c} can be compiled with
846 the switches used for all the other C files, plus @option{-g}.
847 In this specific situation the use of a variable could have been
848 replaced by a reference to the @code{Default_Switches} attribute:
850 @smallexample @c projectfile
851 for ^Switches^Switches^ ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
855 Note the tick (@emph{'}) used to refer to attributes defined in a package.
857 Here is the output of the GPRbuild command using this project:
861 gcc -c -pedantic -g main.c
862 gcc -c -gnaty proc.adb
863 gcc -c -gnaty pack.adb
864 gcc -c -pedantic utils.c
871 The default switches for Ada sources,
872 the default switches for C sources (in the compilation of @file{lib.c}),
873 and the specific switches for @file{main.c} have all been taken into
876 @c ---------------------------------------------
878 @subsection Naming Schemes
879 @c ---------------------------------------------
882 Sometimes an Ada software system is ported from one compilation environment to
883 another (say GNAT), and the file are not named using the default GNAT
884 conventions. Instead of changing all the file names, which for a variety of
885 reasons might not be possible, you can define the relevant file naming scheme
886 in the @b{Naming} package of your project file.
888 The naming scheme has two distinct goals for the project manager: it
889 allows finding of source files when searching in the source
890 directories, and given a source file name it makes it possible to guess
891 the associated language, and thus the compiler to use.
893 Note that the use by the Ada compiler of pragmas Source_File_Name is not
894 supported when using project files. You must use the features described in this
895 paragraph. You can however specify other configuration pragmas.
897 The following attributes can be defined in package @code{Naming}:
901 @cindex @code{Casing}
902 Its value must be one of @code{"lowercase"} (the default if
903 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
904 casing of file names with regards to the Ada unit name. Given an Ada unit
905 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
906 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
907 On Windows, file names are case insensitive, so this attribute is
910 @item @b{Dot_Replacement}:
911 @cindex @code{Dot_Replacement}
912 This attribute specifies the string that should replace the "." in unit
913 names. Its default value is @code{"-"} so that a unit
914 @code{Parent.Child} is expected to be found in the file
915 @file{parent-child.adb}. The replacement string must satisfy the following
916 requirements to avoid ambiguities in the naming scheme:
919 @item It must not be empty
920 @item It cannot start or end with an alphanumeric character
921 @item It cannot be a single underscore
922 @item It cannot start with an underscore followed by an alphanumeric
923 @item It cannot contain a dot @code{'.'} except if the entire string
928 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
929 @cindex @code{Spec_Suffix}
930 @cindex @code{Specification_Suffix}
931 For Ada, these attributes give the suffix used in file names that contain
932 specifications. For other languages, they give the extension for files
933 that contain declaration (header files in C for instance). The attribute
934 is indexed on the language.
935 The two attributes are equivalent, but the latter is obsolescent.
937 If the value of the attribute is the empty string, it indicates to the
938 Project Manager that the only specifications/header files for the language
939 are those specified with attributes @code{Spec} or
940 @code{Specification_Exceptions}.
942 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
943 @code{"^.ads^.ADS^"}.
945 A non empty value must satisfy the following requirements:
948 @item It must include at least one dot
949 @item If @code{Dot_Replacement} is a single dot, then it cannot include
953 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
954 @cindex @code{Body_Suffix}
955 @cindex @code{Implementation_Suffix}
956 These attributes give the extension used for file names that contain
957 code (bodies in Ada). They are indexed on the language. The second
958 version is obsolescent and fully replaced by the first attribute.
960 For each language of a project, one of these two attributes need to be
961 specified, either in the project itself or in the configuration project file.
963 If the value of the attribute is the empty string, it indicates to the
964 Project Manager that the only source files for the language
965 are those specified with attributes @code{Body} or
966 @code{Implementation_Exceptions}.
968 These attributes must satisfy the same requirements as @code{Spec_Suffix}.
969 In addition, they must be different from any of the values in
971 If @code{Body_Suffix ("Ada")} is not specified, then the default is
972 @code{"^.adb^.ADB^"}.
974 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
975 same string, then a file name that ends with the longest of these two
976 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
977 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
979 If the suffix does not start with a '.', a file with a name exactly equal to
980 the suffix will also be part of the project (for instance if you define the
981 suffix as @code{Makefile.in}, a file called @file{Makefile.in} will be part
982 of the project. This capability is usually not interesting when building.
983 However, it might become useful when a project is also used to
984 find the list of source files in an editor, like the GNAT Programming System
987 @item @b{Separate_Suffix}:
988 @cindex @code{Separate_Suffix}
989 This attribute is specific to Ada. It denotes the suffix used in file names
990 that contain separate bodies. If it is not specified, then it defaults to
991 same value as @code{Body_Suffix ("Ada")}.
993 The value of this attribute cannot be the empty string.
995 Otherwise, the same rules apply as for the
996 @code{Body_Suffix} attribute. The only accepted index is "Ada".
998 @item @b{Spec} or @b{Specification}:
1000 @cindex @code{Specification}
1001 This attribute @code{Spec} can be used to define the source file name for a
1002 given Ada compilation unit's spec. The index is the literal name of the Ada
1003 unit (case insensitive). The value is the literal base name of the file that
1004 contains this unit's spec (case sensitive or insensitive depending on the
1005 operating system). This attribute allows the definition of exceptions to the
1006 general naming scheme, in case some files do not follow the usual
1009 When a source file contains several units, the relative position of the unit
1010 can be indicated. The first unit in the file is at position 1
1012 @smallexample @c projectfile
1013 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
1014 for Spec ("top") use "foo.a" at 1;
1015 for Spec ("foo") use "foo.a" at 2;
1018 @item @b{Body} or @b{Implementation}:
1020 @cindex @code{Implementation}
1021 These attribute play the same role as @emph{Spec} for Ada bodies.
1023 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
1024 @cindex @code{Specification_Exceptions}
1025 @cindex @code{Implementation_Exceptions}
1026 These attributes define exceptions to the naming scheme for languages
1027 other than Ada. They are indexed on the language name, and contain
1028 a list of file names respectively for headers and source code.
1033 For example, the following package models the Apex file naming rules:
1035 @smallexample @c projectfile
1038 for Casing use "lowercase";
1039 for Dot_Replacement use ".";
1040 for Spec_Suffix ("Ada") use ".1.ada";
1041 for Body_Suffix ("Ada") use ".2.ada";
1048 For example, the following package models the DEC Ada file naming rules:
1050 @smallexample @c projectfile
1053 for Casing use "lowercase";
1054 for Dot_Replacement use "__";
1055 for Spec_Suffix ("Ada") use "_.ada";
1056 for Body_Suffix ("Ada") use ".ada";
1062 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1063 names in lower case)
1066 @c ---------------------------------------------
1068 @subsection Installation
1069 @c ---------------------------------------------
1072 After building an application or a library it is often required to
1073 install it into the development environment. For instance this step is
1074 required if the library is to be used by another application.
1075 The @command{gprinstall} tool provides an easy way to install
1076 libraries, executable or object code generated during the build. The
1077 @b{Install} package can be used to change the default locations.
1079 The following attributes can be defined in package @code{Install}:
1085 Whether the project is to be installed, values are @code{true}
1086 (default) or @code{false}.
1089 @cindex @code{Artifacts}
1091 An array attribute to declare a set of files not part of the sources
1092 to be installed. The array discriminant is the directory where the
1093 file is to be installed. If a relative directory then Prefix (see
1094 below) is prepended.
1097 @cindex @code{Prefix}
1099 Root directory for the installation.
1101 @item @b{Exec_Subdir}
1103 Subdirectory of @b{Prefix} where executables are to be
1104 installed. Default is @b{bin}.
1106 @item @b{Lib_Subdir}
1108 Subdirectory of @b{Prefix} where directory with the library or object
1109 files is to be installed. Default is @b{lib}.
1111 @item @b{Sources_Subdir}
1113 Subdirectory of @b{Prefix} where directory with sources is to be
1114 installed. Default is @b{include}.
1116 @item @b{Project_Subdir}
1118 Subdirectory of @b{Prefix} where the generated project file is to be
1119 installed. Default is @b{share/gpr}.
1122 @c ---------------------------------------------
1123 @node Distributed support
1124 @subsection Distributed support
1125 @c ---------------------------------------------
1128 For large projects the compilation time can become a limitation in
1129 the development cycle. To cope with that, GPRbuild supports
1130 distributed compilation.
1132 The following attributes can be defined in package @code{Remote}:
1137 @cindex @code{Root_Dir}
1139 Root directory of the project's sources. The default value is the
1140 project's directory.
1144 @c ---------------------------------------------
1145 @node Organizing Projects into Subsystems
1146 @section Organizing Projects into Subsystems
1147 @c ---------------------------------------------
1150 A @b{subsystem} is a coherent part of the complete system to be built. It is
1151 represented by a set of sources and one single object directory. A system can
1152 be composed of a single subsystem when it is simple as we have seen in the
1153 first section. Complex systems are usually composed of several interdependent
1154 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1155 other one is required to build it, and in particular if visibility on some of
1156 the sources of this other subsystem is required. Each subsystem is usually
1157 represented by its own project file.
1159 In this section, the previous example is being extended. Let's assume some
1160 sources of our @code{Build} project depend on other sources.
1161 For instance, when building a graphical interface, it is usual to depend upon
1162 a graphical library toolkit such as GtkAda. Furthermore, we also need
1163 sources from a logging module we had previously written.
1166 * Project Dependencies::
1167 * Cyclic Project Dependencies::
1168 * Sharing Between Projects::
1169 * Global Attributes::
1172 @c ---------------------------------------------
1173 @node Project Dependencies
1174 @subsection Project Dependencies
1175 @c ---------------------------------------------
1178 GtkAda comes with its own project file (appropriately called
1179 @file{gtkada.gpr}), and we will assume we have already built a project
1180 called @file{logging.gpr} for the logging module. With the information provided
1181 so far in @file{build.gpr}, building the application would fail with an error
1182 indicating that the gtkada and logging units that are relied upon by the sources
1183 of this project cannot be found.
1185 This is easily solved by adding the following @b{with} clauses at the beginning
1188 @smallexample @c projectfile
1190 with "a/b/logging.gpr";
1197 @cindex @code{Externally_Built}
1198 When such a project is compiled, @command{gnatmake} will automatically
1199 check the other projects and recompile their sources when needed. It will also
1200 recompile the sources from @code{Build} when needed, and finally create the
1201 executable. In some cases, the implementation units needed to recompile a
1202 project are not available, or come from some third-party and you do not want to
1203 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1204 "true" can be set, indicating to the builder that this project can be assumed
1205 to be up-to-date, and should not be considered for recompilation. In Ada, if
1206 the sources of this externally built project were compiled with another version
1207 of the compiler or with incompatible options, the binder will issue an error.
1209 The project's @code{with} clause has several effects. It provides source
1210 visibility between projects during the compilation process. It also guarantees
1211 that the necessary object files from @code{Logging} and @code{GtkAda} are
1212 available when linking @code{Build}.
1214 As can be seen in this example, the syntax for importing projects is similar
1215 to the syntax for importing compilation units in Ada. However, project files
1216 use literal strings instead of names, and the @code{with} clause identifies
1217 project files rather than packages.
1219 Each literal string after @code{with} is the path
1220 (absolute or relative) to a project file. The @code{.gpr} extension is
1221 optional, although we recommend adding it. If no extension is specified,
1222 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1223 the file is searched for exactly as written in the @code{with} clause,
1224 that is with no extension.
1226 As mentioned above, the path after a @code{with} has to be a literal
1227 string, and you cannot use concatenation, or lookup the value of external
1228 variables to change the directories from which a project is loaded.
1229 A solution if you need something like this is to use aggregate projects
1230 (@pxref{Aggregate Projects}).
1232 @cindex project path
1233 When a relative path or a base name is used, the
1234 project files are searched relative to each of the directories in the
1235 @b{project path}. This path includes all the directories found with the
1236 following algorithm, in that order, as soon as a matching file is found,
1240 @item First, the file is searched relative to the directory that contains the
1241 current project file.
1244 @cindex @code{GPR_PROJECT_PATH_FILE}
1245 @cindex @code{GPR_PROJECT_PATH}
1246 @cindex @code{ADA_PROJECT_PATH}
1247 Then it is searched relative to all the directories specified in the
1248 ^environment variables^logical names^ @b{GPR_PROJECT_PATH_FILE},
1249 @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH} (in that order) if they exist.
1250 The value of @b{GPR_PROJECT_PATH_FILE}, when defined, is the path name of
1251 a text file that contains project directory path names, one per line.
1252 @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH}, when defined, contain
1253 project directory path names separated by directory separators.
1254 @b{ADA_PROJECT_PATH} is used for compatibility, it is recommended to
1255 use @b{GPR_PROJECT_PATH_FILE} or @b{GPR_PROJECT_PATH}.
1257 @item Finally, it is searched relative to the default project directories.
1258 Such directories depends on the tool used. The different locations searched
1259 in the specified order are:
1262 @item @file{<prefix>/<target>/lib/gnat}
1263 (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
1264 @option{--target} is specified)
1265 @item @file{<prefix>/<target>/share/gpr}
1266 (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
1267 @option{--target} is specified)
1268 @item @file{<prefix>/share/gpr/}
1269 (for @command{gnatmake} and @command{gprbuild})
1270 @item @file{<prefix>/lib/gnat/}
1271 (for @command{gnatmake} and @command{gprbuild})
1274 In our example, @file{gtkada.gpr} is found in the predefined directory if
1275 it was installed at the same root as GNAT.
1279 Some tools also support extending the project path from the command line,
1280 generally through the @option{-aP}. You can see the value of the project
1281 path by using the @command{gnatls -v} command.
1283 Any symbolic link will be fully resolved in the directory of the
1284 importing project file before the imported project file is examined.
1286 Any source file in the imported project can be used by the sources of the
1287 importing project, transitively.
1288 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1289 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1290 import @code{C} explicitly. However, this is not recommended, because if
1291 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1292 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1293 that will report such indirect dependencies.
1295 One very important aspect of a project hierarchy is that
1296 @b{a given source can only belong to one project} (otherwise the project manager
1297 would not know which settings apply to it and when to recompile it). It means
1298 that different project files do not usually share source directories or
1299 when they do, they need to specify precisely which project owns which sources
1300 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1301 can each own a source with the same base file name as long as they live in
1302 different directories. The latter is not true for Ada Sources because of the
1303 correlation between source files and Ada units.
1305 @c ---------------------------------------------
1306 @node Cyclic Project Dependencies
1307 @subsection Cyclic Project Dependencies
1308 @c ---------------------------------------------
1311 Cyclic dependencies are mostly forbidden:
1312 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1313 is not allowed to import @code{A}. However, there are cases when cyclic
1314 dependencies would be beneficial. For these cases, another form of import
1315 between projects exists: the @b{limited with}. A project @code{A} that
1316 imports a project @code{B} with a straight @code{with} may also be imported,
1317 directly or indirectly, by @code{B} through a @code{limited with}.
1319 The difference between straight @code{with} and @code{limited with} is that
1320 the name of a project imported with a @code{limited with} cannot be used in the
1321 project importing it. In particular, its packages cannot be renamed and
1322 its variables cannot be referred to.
1324 @smallexample @c 0projectfile
1328 For Exec_Dir use B'Exec_Dir; -- ok
1331 limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
1333 For Exec_Dir use A'Exec_Dir; -- not ok
1340 limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
1342 For Exec_Dir use A'Exec_Dir; -- not ok
1346 @c ---------------------------------------------
1347 @node Sharing Between Projects
1348 @subsection Sharing Between Projects
1349 @c ---------------------------------------------
1352 When building an application, it is common to have similar needs in several of
1353 the projects corresponding to the subsystems under construction. For instance,
1354 they will all have the same compilation switches.
1356 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1357 switches for all sources of a subsystem is simple: it is just a matter of
1358 adding a @code{Compiler.Default_Switches} attribute to each project files with
1359 the same value. Of course, that means duplication of data, and both places need
1360 to be changed in order to recompile the whole application with different
1361 switches. It can become a real problem if there are many subsystems and thus
1362 many project files to edit.
1364 There are two main approaches to avoiding this duplication:
1367 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1368 to reference the attribute in Logging, either through a package renaming,
1369 or by referencing the attribute. The following example shows both cases:
1371 @smallexample @c projectfile
1374 for ^Switches^Switches^ ("Ada")
1378 for ^Switches^Switches^ ("Ada")
1385 package Compiler renames Logging.Compiler;
1387 for ^Switches^Switches^ ("Ada") use Logging.Binder'Switches ("Ada");
1393 The solution used for @code{Compiler} gets the same value for all
1394 attributes of the package, but you cannot modify anything from the
1395 package (adding extra switches or some exceptions). The second
1396 version is more flexible, but more verbose.
1398 If you need to refer to the value of a variable in an imported
1399 project, rather than an attribute, the syntax is similar but uses
1400 a "." rather than an apostrophe. For instance:
1402 @smallexample @c projectfile
1405 Var1 := Imported.Var;
1409 @item The second approach is to define the switches in a third project.
1410 That project is setup without any sources (so that, as opposed to
1411 the first example, none of the project plays a special role), and
1412 will only be used to define the attributes. Such a project is
1413 typically called @file{shared.gpr}.
1415 @smallexample @c projectfile
1416 abstract project Shared is
1417 for Source_Files use (); -- no sources
1419 for ^Switches^Switches^ ("Ada")
1426 package Compiler renames Shared.Compiler;
1431 package Compiler renames Shared.Compiler;
1436 As for the first example, we could have chosen to set the attributes
1437 one by one rather than to rename a package. The reason we explicitly
1438 indicate that @code{Shared} has no sources is so that it can be created
1439 in any directory and we are sure it shares no sources with @code{Build}
1440 or @code{Logging}, which of course would be invalid.
1442 @cindex project qualifier
1443 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1444 This qualifier is optional, but helps convey the message that we do not
1445 intend this project to have sources (@pxref{Qualified Projects} for
1449 @c ---------------------------------------------
1450 @node Global Attributes
1451 @subsection Global Attributes
1452 @c ---------------------------------------------
1455 We have already seen many examples of attributes used to specify a special
1456 option of one of the tools involved in the build process. Most of those
1457 attributes are project specific. That it to say, they only affect the invocation
1458 of tools on the sources of the project where they are defined.
1460 There are a few additional attributes that apply to all projects in a
1461 hierarchy as long as they are defined on the "main" project.
1462 The main project is the project explicitly mentioned on the command-line.
1463 The project hierarchy is the "with"-closure of the main project.
1465 Here is a list of commonly used global attributes:
1468 @item @b{Builder.Global_Configuration_Pragmas}:
1469 @cindex @code{Global_Configuration_Pragmas}
1470 This attribute points to a file that contains configuration pragmas
1471 to use when building executables. These pragmas apply for all
1472 executables built from this project hierarchy. As we have seen before,
1473 additional pragmas can be specified on a per-project basis by setting the
1474 @code{Compiler.Local_Configuration_Pragmas} attribute.
1476 @item @b{Builder.Global_Compilation_Switches}:
1477 @cindex @code{Global_Compilation_Switches}
1478 This attribute is a list of compiler switches to use when compiling any
1479 source file in the project hierarchy. These switches are used in addition
1480 to the ones defined in the @code{Compiler} package, which only apply to
1481 the sources of the corresponding project. This attribute is indexed on
1482 the name of the language.
1486 Using such global capabilities is convenient. It can also lead to unexpected
1487 behavior. Especially when several subsystems are shared among different main
1488 projects and the different global attributes are not
1489 compatible. Note that using aggregate projects can be a safer and more powerful
1490 replacement to global attributes.
1492 @c ---------------------------------------------
1493 @node Scenarios in Projects
1494 @section Scenarios in Projects
1495 @c ---------------------------------------------
1498 Various aspects of the projects can be modified based on @b{scenarios}. These
1499 are user-defined modes that change the behavior of a project. Typical
1500 examples are the setup of platform-specific compiler options, or the use of
1501 a debug and a release mode (the former would activate the generation of debug
1502 information, when the second will focus on improving code optimization).
1504 Let's enhance our example to support a debug and a release modes.The issue is to
1505 let the user choose what kind of system he is building:
1506 use @option{-g} as compiler switches in debug mode and @option{^-O2^-O2^}
1507 in release mode. We will also setup the projects so that we do not share the
1508 same object directory in both modes, otherwise switching from one to the other
1509 might trigger more recompilations than needed or mix objects from the 2 modes.
1511 One naive approach is to create two different project files, say
1512 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1513 attributes as explained in previous sections. This solution does not scale well,
1514 because in presence of multiple projects depending on each other,
1515 you will also have to duplicate the complete hierarchy and adapt the project
1516 files to point to the right copies.
1519 Instead, project files support the notion of scenarios controlled
1520 by external values. Such values can come from several sources (in decreasing
1524 @item @b{Command line}:
1526 When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1527 extra @option{-X} switches to define the external value. In
1528 our case, the command line might look like
1531 gnatmake -Pbuild.gpr -Xmode=debug
1532 or gnatmake -Pbuild.gpr -Xmode=release
1535 @item @b{^Environment variables^Logical names^}:
1536 When the external value does not come from the command line, it can come from
1537 the value of ^environment variables^logical names^ of the appropriate name.
1538 In our case, if ^an environment variable^a logical name^ called "mode"
1539 exist, its value will be taken into account.
1541 @item @b{External function second parameter}
1545 @cindex @code{external}
1546 We now need to get that value in the project. The general form is to use
1547 the predefined function @b{external} which returns the current value of
1548 the external. For instance, we could setup the object directory to point to
1549 either @file{obj/debug} or @file{obj/release} by changing our project to
1551 @smallexample @c projectfile
1553 for Object_Dir use "obj/" & external ("mode", "debug");
1559 The second parameter to @code{external} is optional, and is the default
1560 value to use if "mode" is not set from the command line or the environment.
1562 In order to set the switches according to the different scenarios, other
1563 constructs have to be introduced such as typed variables and case constructions.
1565 @cindex typed variable
1566 @cindex case construction
1567 A @b{typed variable} is a variable that
1568 can take only a limited number of values, similar to an enumeration in Ada.
1569 Such a variable can then be used in a @b{case construction} and create conditional
1570 sections in the project. The following example shows how this can be done:
1572 @smallexample @c projectfile
1574 type Mode_Type is ("debug", "release"); -- all possible values
1575 Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1580 for ^Switches^Switches^ ("Ada")
1583 for ^Switches^Switches^ ("Ada")
1591 The project has suddenly grown in size, but has become much more flexible.
1592 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1593 any other value is read from the environment, an error is reported and the
1594 project is considered as invalid.
1596 The @code{Mode} variable is initialized with an external value
1597 defaulting to @code{"debug"}. This default could be omitted and that would
1598 force the user to define the value. Finally, we can use a case construction to set the
1599 switches depending on the scenario the user has chosen.
1601 Most aspects of the projects can depend on scenarios. The notable exception
1602 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1604 Scenarios work the same way with @b{project hierarchies}: you can either
1605 duplicate a variable similar to @code{Mode} in each of the project (as long
1606 as the first argument to @code{external} is always the same and the type is
1607 the same), or simply set the variable in the @file{shared.gpr} project
1608 (@pxref{Sharing Between Projects}).
1610 @c ---------------------------------------------
1611 @node Library Projects
1612 @section Library Projects
1613 @c ---------------------------------------------
1616 So far, we have seen examples of projects that create executables. However,
1617 it is also possible to create libraries instead. A @b{library} is a specific
1618 type of subsystem where, for convenience, objects are grouped together
1619 using system-specific means such as archives or windows DLLs.
1621 Library projects provide a system- and language-independent way of building both @b{static}
1622 and @b{dynamic} libraries. They also support the concept of @b{standalone
1623 libraries} (SAL) which offers two significant properties: the elaboration
1624 (e.g. initialization) of the library is either automatic or very simple;
1626 implementation part of the library implies minimal post-compilation actions on
1627 the complete system and potentially no action at all for the rest of the
1628 system in the case of dynamic SALs.
1630 There is a restriction on shared library projects: by default, they are only
1631 allowed to import other shared library projects. They are not allowed to
1632 import non library projects or static library projects.
1634 The GNAT Project Manager takes complete care of the library build, rebuild and
1635 installation tasks, including recompilation of the source files for which
1636 objects do not exist or are not up to date, assembly of the library archive, and
1637 installation of the library (i.e., copying associated source, object and
1638 @file{ALI} files to the specified location).
1641 * Building Libraries::
1642 * Using Library Projects::
1643 * Stand-alone Library Projects::
1644 * Installing a library with project files::
1647 @c ---------------------------------------------
1648 @node Building Libraries
1649 @subsection Building Libraries
1650 @c ---------------------------------------------
1653 Let's enhance our example and transform the @code{logging} subsystem into a
1654 library. In order to do so, a few changes need to be made to @file{logging.gpr}.
1655 A number of specific attributes needs to be defined: at least @code{Library_Name}
1656 and @code{Library_Dir}; in addition, a number of other attributes can be used
1657 to specify specific aspects of the library. For readability, it is also
1658 recommended (although not mandatory), to use the qualifier @code{library} in
1659 front of the @code{project} keyword.
1662 @item @b{Library_Name}:
1663 @cindex @code{Library_Name}
1664 This attribute is the name of the library to be built. There is no
1665 restriction on the name of a library imposed by the project manager, except
1666 for stand-alone libraries whose names must follow the syntax of Ada
1667 identifiers; however, there may be system specific restrictions on the name.
1668 In general, it is recommended to stick to alphanumeric characters (and
1669 possibly single underscores) to help portability.
1671 @item @b{Library_Dir}:
1672 @cindex @code{Library_Dir}
1673 This attribute is the path (absolute or relative) of the directory where
1674 the library is to be installed. In the process of building a library,
1675 the sources are compiled, the object files end up in the explicit or
1676 implicit @code{Object_Dir} directory. When all sources of a library
1677 are compiled, some of the compilation artifacts, including the library itself,
1678 are copied to the library_dir directory. This directory must exists and be
1679 writable. It must also be different from the object directory so that cleanup
1680 activities in the Library_Dir do not affect recompilation needs.
1684 Here is the new version of @file{logging.gpr} that makes it a library:
1686 @smallexample @c projectfile
1687 library project Logging is -- "library" is optional
1688 for Library_Name use "logging"; -- will create "liblogging.a" on Unix
1689 for Object_Dir use "obj";
1690 for Library_Dir use "lib"; -- different from object_dir
1695 Once the above two attributes are defined, the library project is valid and
1696 is enough for building a library with default characteristics.
1697 Other library-related attributes can be used to change the defaults:
1700 @item @b{Library_Kind}:
1701 @cindex @code{Library_Kind}
1702 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1703 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1704 which kind of library should be built (the default is to build a
1705 static library, that is an archive of object files that can potentially
1706 be linked into a static executable). When the library is set to be dynamic,
1707 a separate image is created that will be loaded independently, usually
1708 at the start of the main program execution. Support for dynamic libraries is
1709 very platform specific, for instance on Windows it takes the form of a DLL
1710 while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1711 @file{.so}. Library project files, on the other hand, can be written in
1712 a platform independent way so that the same project file can be used to build
1713 a library on different operating systems.
1715 If you need to build both a static and a dynamic library, it is recommended
1716 use two different object directories, since in some cases some extra code
1717 needs to be generated for the latter. For such cases, one can
1718 either define two different project files, or a single one which uses scenarios
1719 to indicate the various kinds of library to be built and their
1720 corresponding object_dir.
1722 @cindex @code{Library_ALI_Dir}
1723 @item @b{Library_ALI_Dir}:
1724 This attribute may be specified to indicate the directory where the ALI
1725 files of the library are installed. By default, they are copied into the
1726 @code{Library_Dir} directory, but as for the executables where we have a
1727 separate @code{Exec_Dir} attribute, you might want to put them in a separate
1728 directory since there can be hundreds of them. The same restrictions as for
1729 the @code{Library_Dir} attribute apply.
1731 @cindex @code{Library_Version}
1732 @item @b{Library_Version}:
1733 This attribute is platform dependent, and has no effect on VMS and Windows.
1734 On Unix, it is used only for dynamic libraries as the internal
1735 name of the library (the @code{"soname"}). If the library file name (built
1736 from the @code{Library_Name}) is different from the @code{Library_Version},
1737 then the library file will be a symbolic link to the actual file whose name
1738 will be @code{Library_Version}. This follows the usual installation schemes
1739 for dynamic libraries on many Unix systems.
1741 @smallexample @c projectfile
1745 for Library_Dir use "lib";
1746 for Library_Name use "logging";
1747 for Library_Kind use "dynamic";
1748 for Library_Version use "liblogging.so." & Version;
1754 After the compilation, the directory @file{lib} will contain both a
1755 @file{libdummy.so.1} library and a symbolic link to it called
1758 @cindex @code{Library_GCC}
1759 @item @b{Library_GCC}:
1760 This attribute is the name of the tool to use instead of "gcc" to link shared
1761 libraries. A common use of this attribute is to define a wrapper script that
1762 accomplishes specific actions before calling gcc (which itself is calling the
1763 linker to build the library image).
1765 @item @b{Library_Options}:
1766 @cindex @code{Library_Options}
1767 This attribute may be used to specify additional switches (last switches)
1768 when linking a shared library.
1770 It may also be used to add foreign object files in a static library.
1771 Each string in Library_Options is an absolute or relative path of an object
1772 file. When a relative path, it is relative to the object directory.
1774 @item @b{Leading_Library_Options}:
1775 @cindex @code{Leading_Library_Options}
1776 This attribute, that is taken into account only by @command{gprbuild}, may be
1777 used to specified leading options (first switches) when linking a shared
1780 @cindex @code{Linker_Options}
1781 @item @b{Linker.Linker_Options}:
1782 This attribute specifies additional switches to be given to the linker when
1783 linking an executable. It is ignored when defined in the main project and
1784 taken into account in all other projects that are imported directly or
1785 indirectly. These switches complement the @code{Linker.Switches}
1786 defined in the main project. This is useful when a particular subsystem
1787 depends on an external library: adding this dependency as a
1788 @code{Linker_Options} in the project of the subsystem is more convenient than
1789 adding it to all the @code{Linker.Switches} of the main projects that depend
1790 upon this subsystem.
1793 @c ---------------------------------------------
1794 @node Using Library Projects
1795 @subsection Using Library Projects
1796 @c ---------------------------------------------
1799 When the builder detects that a project file is a library project file, it
1800 recompiles all sources of the project that need recompilation and rebuild the
1801 library if any of the sources have been recompiled. It then groups all object
1802 files into a single file, which is a shared or a static library. This library
1803 can later on be linked with multiple executables. Note that the use
1804 of shard libraries reduces the size of the final executable and can also reduce
1805 the memory footprint at execution time when the library is shared among several
1808 It is also possible to build @b{multi-language libraries}. When using
1809 @command{gprbuild} as a builder, multi-language library projects allow naturally
1810 the creation of multi-language libraries . @command{gnatmake}, does not try to
1811 compile non Ada sources. However, when the project is multi-language, it will
1812 automatically link all object files found in the object directory, whether or
1813 not they were compiled from an Ada source file. This specific behavior does not
1814 apply to Ada-only projects which only take into account the objects
1815 corresponding to the sources of the project.
1817 A non-library project can import a library project. When the builder is invoked
1818 on the former, the library of the latter is only rebuilt when absolutely
1819 necessary. For instance, if a unit of the
1820 library is not up-to-date but non of the executables need this unit, then the
1821 unit is not recompiled and the library is not reassembled.
1822 For instance, let's assume in our example that logging has the following
1823 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1824 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1825 @file{liblogging} will be rebuilt when compiling all the sources of
1826 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1827 include a @code{"with Log1"}.
1829 To ensure that all the sources in the @code{Logging} library are
1830 up to date, and that all the sources of @code{Build} are also up to date,
1831 the following two commands needs to be used:
1834 gnatmake -Plogging.gpr
1835 gnatmake -Pbuild.gpr
1839 All @file{ALI} files will also be copied from the object directory to the
1840 library directory. To build executables, @command{gnatmake} will use the
1841 library rather than the individual object files.
1844 Library projects can also be useful to describe a library that need to be used
1845 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1846 of the library sources are not available. Such library projects need simply to
1847 use the @code{Externally_Built} attribute as in the example below:
1849 @smallexample @c projectfile
1850 library project Extern_Lib is
1851 for Languages use ("Ada", "C");
1852 for Source_Dirs use ("lib_src");
1853 for Library_Dir use "lib2";
1854 for Library_Kind use "dynamic";
1855 for Library_Name use "l2";
1856 for Externally_Built use "true"; -- <<<<
1861 In the case of externally built libraries, the @code{Object_Dir}
1862 attribute does not need to be specified because it will never be
1865 The main effect of using such an externally built library project is mostly to
1866 affect the linker command in order to reference the desired library. It can
1867 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1868 in the project corresponding to the subsystem needing this external library.
1869 This latter method is more straightforward in simple cases but when several
1870 subsystems depend upon the same external library, finding the proper place
1871 for the @code{Linker.Linker_Options} might not be easy and if it is
1872 not placed properly, the final link command is likely to present ordering issues.
1873 In such a situation, it is better to use the externally built library project
1874 so that all other subsystems depending on it can declare this dependency thanks
1875 to a project @code{with} clause, which in turn will trigger the builder to find
1876 the proper order of libraries in the final link command.
1879 @c ---------------------------------------------
1880 @node Stand-alone Library Projects
1881 @subsection Stand-alone Library Projects
1882 @c ---------------------------------------------
1885 @cindex standalone libraries
1886 A @b{stand-alone library} is a library that contains the necessary code to
1887 elaborate the Ada units that are included in the library. A stand-alone
1888 library is a convenient way to add an Ada subsystem to a more global system
1889 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1890 transparent. However, stand-alone libraries are also useful when the main is in
1891 Ada: they provide a means for minimizing relinking & redeployment of complex
1892 systems when localized changes are made.
1894 The name of a stand-alone library, specified with attribute
1895 @code{Library_Name}, must have the syntax of an Ada identifier.
1897 The most prominent characteristic of a stand-alone library is that it offers a
1898 distinction between interface units and implementation units. Only the former
1899 are visible to units outside the library. A stand-alone library project is thus
1900 characterised by a third attribute, usually @b{Library_Interface}, in addition
1901 to the two attributes that make a project a Library Project
1902 (@code{Library_Name} and @code{Library_Dir}). This third attribute may also be
1903 @b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada
1904 and takes a list of units as parameter. @b{Interfaces} works for any supported
1905 language and takes a list of sources as parameter.
1908 @item @b{Library_Interface}:
1909 @cindex @code{Library_Interface}
1910 This attribute defines an explicit subset of the units of the project. Units
1911 from projects importing this library project may only "with" units whose
1912 sources are listed in the @code{Library_Interface}. Other sources are
1913 considered implementation units.
1915 @smallexample @c projectfile
1917 for Library_Dir use "lib";
1918 for Library_Name use "loggin";
1919 for Library_Interface use ("lib1", "lib2"); -- unit names
1923 @item @b{Interfaces}
1924 This attribute defines an explicit subset of the source files of a project.
1925 Sources from projects importing this project, can only depend on sources from
1926 this subset. This attribute can be used on non library projects. It can also
1927 be used as a replacement for attribute @code{Library_Interface}, in which
1928 case, units have to be replaced by source files. For multi-language library
1929 projects, it is the only way to make the project a Stand-Alone Library project
1930 whose interface is not purely Ada.
1932 @item @b{Library_Standalone}:
1933 @cindex @code{Library_Standalone}
1934 This attribute defines the kind of standalone library to
1935 build. Values are either @code{standard} (the default), @code{no} or
1936 @code{encapsulated}. When @code{standard} is used the code to elaborate and
1937 finalize the library is embedded, when @code{encapsulated} is used the
1938 library can furthermore only depends on static libraries (including
1939 the GNAT runtime). This attribute can be set to @code{no} to make it clear
1940 that the library should not be standalone in which case the
1941 @code{Library_Interface} should not defined. Note that this attribute
1942 only applies to shared libraries, so @code{Library_Kind} must be set
1945 @smallexample @c projectfile
1947 for Library_Dir use "lib";
1948 for Library_Name use "loggin";
1949 for Library_Kind use "dynamic";
1950 for Library_Interface use ("lib1", "lib2"); -- unit names
1951 for Library_Standalone use "encapsulated";
1957 In order to include the elaboration code in the stand-alone library, the binder
1958 is invoked on the closure of the library units creating a package whose name
1959 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1960 This binder-generated package includes @b{initialization} and @b{finalization}
1961 procedures whose names depend on the library name (@code{logginginit} and
1962 @code{loggingfinal} in the example). The object corresponding to this package is
1963 included in the library.
1966 @item @b{Library_Auto_Init}:
1967 @cindex @code{Library_Auto_Init}
1968 A dynamic stand-alone Library is automatically initialized
1969 if automatic initialization of Stand-alone Libraries is supported on the
1970 platform and if attribute @b{Library_Auto_Init} is not specified or
1971 is specified with the value "true". A static Stand-alone Library is never
1972 automatically initialized. Specifying "false" for this attribute
1973 prevent automatic initialization.
1975 When a non-automatically initialized stand-alone library is used in an
1976 executable, its initialization procedure must be called before any service of
1977 the library is used. When the main subprogram is in Ada, it may mean that the
1978 initialization procedure has to be called during elaboration of another
1981 @item @b{Library_Dir}:
1982 @cindex @code{Library_Dir}
1983 For a stand-alone library, only the @file{ALI} files of the interface units
1984 (those that are listed in attribute @code{Library_Interface}) are copied to
1985 the library directory. As a consequence, only the interface units may be
1986 imported from Ada units outside of the library. If other units are imported,
1987 the binding phase will fail.
1989 @item @b{Binder.Default_Switches}:
1990 When a stand-alone library is bound, the switches that are specified in
1991 the attribute @b{Binder.Default_Switches ("Ada")} are
1992 used in the call to @command{gnatbind}.
1994 @item @b{Library_Src_Dir}:
1995 @cindex @code{Library_Src_Dir}
1996 This attribute defines the location (absolute or relative to the project
1997 directory) where the sources of the interface units are copied at
1999 These sources includes the specs of the interface units along with the closure
2000 of sources necessary to compile them successfully. That may include bodies and
2001 subunits, when pragmas @code{Inline} are used, or when there is a generic
2002 units in the spec. This directory cannot point to the object directory or
2003 one of the source directories, but it can point to the library directory,
2004 which is the default value for this attribute.
2006 @item @b{Library_Symbol_Policy}:
2007 @cindex @code{Library_Symbol_Policy}
2008 This attribute controls the export of symbols and, on some platforms (like
2009 VMS) that have the notions of major and minor IDs built in the library
2010 files, it controls the setting of these IDs. It is not supported on all
2011 platforms (where it will just have no effect). It may have one of the
2015 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
2016 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
2017 is not defined, then it is equivalent to policy "autonomous". If there
2018 are exported symbols in the reference symbol file that are not in the
2019 object files of the interfaces, the major ID of the library is increased.
2020 If there are symbols in the object files of the interfaces that are not
2021 in the reference symbol file, these symbols are put at the end of the list
2022 in the newly created symbol file and the minor ID is increased.
2023 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
2024 defined. The library will fail to build if the exported symbols in the
2025 object files of the interfaces do not match exactly the symbol in the
2027 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
2028 The library will fail to build if there are symbols in the symbol file that
2029 are not in the exported symbols of the object files of the interfaces.
2030 Additional symbols in the object files are not added to the symbol file.
2031 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
2032 must designate an existing file in the object directory. This symbol file
2033 is passed directly to the underlying linker without any symbol processing.
2037 @item @b{Library_Reference_Symbol_File}
2038 @cindex @code{Library_Reference_Symbol_File}
2039 This attribute may define the path name of a reference symbol file that is
2040 read when the symbol policy is either "compliant" or "controlled", on
2041 platforms that support symbol control, such as VMS, when building a
2042 stand-alone library. The path may be an absolute path or a path relative
2043 to the project directory.
2045 @item @b{Library_Symbol_File}
2046 @cindex @code{Library_Symbol_File}
2047 This attribute may define the name of the symbol file to be created when
2048 building a stand-alone library when the symbol policy is either "compliant",
2049 "controlled" or "restricted", on platforms that support symbol control,
2050 such as VMS. When symbol policy is "direct", then a file with this name
2051 must exist in the object directory.
2054 @c ---------------------------------------------
2055 @node Installing a library with project files
2056 @subsection Installing a library with project files
2057 @c ---------------------------------------------
2060 When using project files, a usable version of the library is created in the
2061 directory specified by the @code{Library_Dir} attribute of the library
2062 project file. Thus no further action is needed in order to make use of
2063 the libraries that are built as part of the general application build.
2065 You may want to install a library in a context different from where the library
2066 is built. This situation arises with third party suppliers, who may want
2067 to distribute a library in binary form where the user is not expected to be
2068 able to recompile the library. The simplest option in this case is to provide
2069 a project file slightly different from the one used to build the library, by
2070 using the @code{externally_built} attribute. @ref{Using Library Projects}
2072 Another option is to use @command{gprinstall} to install the library in a
2073 different context than the build location. A project to use this library is
2074 generated automatically by @command{gprinstall} which also copy, in the install
2075 location, the minimum set of sources needed to use the library.
2078 @c ---------------------------------------------
2079 @node Project Extension
2080 @section Project Extension
2081 @c ---------------------------------------------
2084 During development of a large system, it is sometimes necessary to use
2085 modified versions of some of the source files, without changing the original
2086 sources. This can be achieved through the @b{project extension} facility.
2088 Suppose for instance that our example @code{Build} project is built every night
2089 for the whole team, in some shared directory. A developer usually need to work
2090 on a small part of the system, and might not want to have a copy of all the
2091 sources and all the object files (mostly because that would require too much
2092 disk space, time to recompile everything). He prefers to be able to override
2093 some of the source files in his directory, while taking advantage of all the
2094 object files generated at night.
2096 Another example can be taken from large software systems, where it is common to have
2097 multiple implementations of a common interface; in Ada terms, multiple
2098 versions of a package body for the same spec. For example, one implementation
2099 might be safe for use in tasking programs, while another might only be used
2100 in sequential applications. This can be modeled in GNAT using the concept
2101 of @emph{project extension}. If one project (the ``child'') @emph{extends}
2102 another project (the ``parent'') then by default all source files of the
2103 parent project are inherited by the child, but the child project can
2104 override any of the parent's source files with new versions, and can also
2105 add new files or remove unnecessary ones.
2106 This facility is the project analog of a type extension in
2107 object-oriented programming. Project hierarchies are permitted (an extending
2108 project may itself be extended), and a project that
2109 extends a project can also import other projects.
2111 A third example is that of using project extensions to provide different
2112 versions of the same system. For instance, assume that a @code{Common}
2113 project is used by two development branches. One of the branches has now
2114 been frozen, and no further change can be done to it or to @code{Common}.
2115 However, the other development branch still needs evolution of @code{Common}.
2116 Project extensions provide a flexible solution to create a new version
2117 of a subsystem while sharing and reusing as much as possible from the original
2120 A project extension inherits implicitly all the sources and objects from the
2121 project it extends. It is possible to create a new version of some of the
2122 sources in one of the additional source dirs of the extending project. Those new
2123 versions hide the original versions. Adding new sources or removing existing
2124 ones is also possible. Here is an example on how to extend the project
2125 @code{Build} from previous examples:
2127 @smallexample @c projectfile
2128 project Work extends "../bld/build.gpr" is
2133 The project after @b{extends} is the one being extended. As usual, it can be
2134 specified using an absolute path, or a path relative to any of the directories
2135 in the project path (@pxref{Project Dependencies}). This project does not
2136 specify source or object directories, so the default value for these attribute
2137 will be used that is to say the current directory (where project @code{Work} is
2138 placed). We can already compile that project with
2145 If no sources have been placed in the current directory, this command
2146 won't do anything, since this project does not change the
2147 sources it inherited from @code{Build}, therefore all the object files
2148 in @code{Build} and its dependencies are still valid and are reused
2151 Suppose we now want to supply an alternate version of @file{pack.adb}
2152 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
2153 We can create the new file Work's current directory (likely
2154 by copying the one from the @code{Build} project and making changes to
2155 it. If new packages are needed at the same time, we simply create
2156 new files in the source directory of the extending project.
2158 When we recompile, @command{gnatmake} will now automatically recompile
2159 this file (thus creating @file{pack.o} in the current directory) and
2160 any file that depends on it (thus creating @file{proc.o}). Finally, the
2161 executable is also linked locally.
2163 Note that we could have obtained the desired behavior using project import
2164 rather than project inheritance. A @code{base} project would contain the
2165 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
2166 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
2167 cannot contain the original version of @file{pack.adb} otherwise there would be
2168 2 versions of the same unit in the closure of the project and this is not
2169 allowed. Generally speaking, it is not recommended to put the spec and the
2170 body of a unit in different projects since this affects their autonomy and
2173 In a project file that extends another project, it is possible to
2174 indicate that an inherited source is @b{not part} of the sources of the
2175 extending project. This is necessary sometimes when a package spec has
2176 been overridden and no longer requires a body: in this case, it is
2177 necessary to indicate that the inherited body is not part of the sources
2178 of the project, otherwise there will be a compilation error
2179 when compiling the spec.
2181 @cindex @code{Excluded_Source_Files}
2182 @cindex @code{Excluded_Source_List_File}
2183 For that purpose, the attribute @b{Excluded_Source_Files} is used.
2184 Its value is a list of file names.
2185 It is also possible to use attribute @code{Excluded_Source_List_File}.
2186 Its value is the path of a text file containing one file name per
2189 @smallexample @c @projectfile
2190 project Work extends "../bld/build.gpr" is
2191 for Source_Files use ("pack.ads");
2192 -- New spec of Pkg does not need a completion
2193 for Excluded_Source_Files use ("pack.adb");
2198 All packages that are not declared in the extending project are inherited from
2199 the project being extended, with their attributes, with the exception of
2200 @code{Linker'Linker_Options} which is never inherited. In particular, an
2201 extending project retains all the switches specified in the project being
2204 At the project level, if they are not declared in the extending project, some
2205 attributes are inherited from the project being extended. They are:
2206 @code{Languages}, @code{Main} (for a root non library project) and
2207 @code{Library_Name} (for a project extending a library project)
2210 * Project Hierarchy Extension::
2213 @c ---------------------------------------------
2214 @node Project Hierarchy Extension
2215 @subsection Project Hierarchy Extension
2216 @c ---------------------------------------------
2219 One of the fundamental restrictions in project extension is the following:
2220 @b{A project is not allowed to import directly or indirectly at the same time an
2221 extending project and one of its ancestors}.
2223 By means of example, consider the following hierarchy of projects.
2226 a.gpr contains package A1
2227 b.gpr, imports a.gpr and contains B1, which depends on A1
2228 c.gpr, imports b.gpr and contains C1, which depends on B1
2232 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2233 create several extending projects:
2236 a_ext.gpr which extends a.gpr, and overrides A1
2237 b_ext.gpr which extends b.gpr and imports a_ext.gpr
2238 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2242 @smallexample @c projectfile
2243 project A_Ext extends "a.gpr" is
2244 for Source_Files use ("a1.adb", "a1.ads");
2248 project B_Ext extends "b.gpr" is
2252 project C_Ext extends "c.gpr" is
2253 for Source_Files use ("c1.adb");
2258 The extension @file{b_ext.gpr} is required, even though we are not overriding
2259 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2260 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2263 When extending a large system spanning multiple projects, it is often
2264 inconvenient to extend every project in the hierarchy that is impacted by a
2265 small change introduced in a low layer. In such cases, it is possible to create
2266 an @b{implicit extension} of entire hierarchy using @b{extends all}
2269 When the project is extended using @code{extends all} inheritance, all projects
2270 that are imported by it, both directly and indirectly, are considered virtually
2271 extended. That is, the project manager creates implicit projects
2272 that extend every project in the hierarchy; all these implicit projects do not
2273 control sources on their own and use the object directory of
2274 the "extending all" project.
2276 It is possible to explicitly extend one or more projects in the hierarchy
2277 in order to modify the sources. These extending projects must be imported by
2278 the "extending all" project, which will replace the corresponding virtual
2279 projects with the explicit ones.
2281 When building such a project hierarchy extension, the project manager will
2282 ensure that both modified sources and sources in implicit extending projects
2283 that depend on them, are recompiled.
2285 Thus, in our example we could create the following projects instead:
2288 a_ext.gpr, extends a.gpr and overrides A1
2289 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2294 @smallexample @c projectfile
2295 project A_Ext extends "a.gpr" is
2296 for Source_Files use ("a1.adb", "a1.ads");
2300 project C_Ext extends all "c.gpr" is
2301 for Source_Files use ("c1.adb");
2306 When building project @file{c_ext.gpr}, the entire modified project space is
2307 considered for recompilation, including the sources of @file{b.gpr} that are
2308 impacted by the changes in @code{A1} and @code{C1}.
2310 @c ---------------------------------------------
2311 @node Aggregate Projects
2312 @section Aggregate Projects
2313 @c ---------------------------------------------
2317 Aggregate projects are an extension of the project paradigm, and are
2318 meant to solve a few specific use cases that cannot be solved directly
2319 using standard projects. This section will go over a few of these use
2320 cases to try to explain what you can use aggregate projects for.
2323 * Building all main programs from a single project tree::
2324 * Building a set of projects with a single command::
2325 * Define a build environment::
2326 * Performance improvements in builder::
2327 * Syntax of aggregate projects::
2328 * package Builder in aggregate projects::
2331 @c -----------------------------------------------------------
2332 @node Building all main programs from a single project tree
2333 @subsection Building all main programs from a single project tree
2334 @c -----------------------------------------------------------
2336 Most often, an application is organized into modules and submodules,
2337 which are very conveniently represented as a project tree or graph
2338 (the root project A @code{with}s the projects for each modules (say B and C),
2339 which in turn @code{with} projects for submodules.
2341 Very often, modules will build their own executables (for testing
2342 purposes for instance), or libraries (for easier reuse in various
2345 However, if you build your project through @command{gnatmake} or
2346 @command{gprbuild}, using a syntax similar to
2352 this will only rebuild the main programs of project A, not those of the
2353 imported projects B and C. Therefore you have to spawn several
2354 @command{gnatmake} commands, one per project, to build all executables.
2355 This is a little inconvenient, but more importantly is inefficient
2356 because @command{gnatmake} needs to do duplicate work to ensure that sources are
2357 up-to-date, and cannot easily compile things in parallel when using
2360 Also libraries are always rebuilt when building a project.
2362 You could therefore define an aggregate project Agg that groups A, B
2363 and C. Then, when you build with
2369 this will build all mains from A, B and C.
2371 @smallexample @c projectfile
2372 aggregate project Agg is
2373 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2377 If B or C do not define any main program (through their Main
2378 attribute), all their sources are built. When you do not group them
2379 in the aggregate project, only those sources that are needed by A
2382 If you add a main to a project P not already explicitly referenced in the
2383 aggregate project, you will need to add "p.gpr" in the list of project
2384 files for the aggregate project, or the main will not be built when
2385 building the aggregate project.
2387 Aggregate projects are only supported with @command{gprbuild}, but not with
2390 @c ---------------------------------------------------------
2391 @node Building a set of projects with a single command
2392 @subsection Building a set of projects with a single command
2393 @c ---------------------------------------------------------
2395 One other case is when you have multiple applications and libraries
2396 that are built independently from each other (but can be built in
2397 parallel). For instance, you have a project tree rooted at A, and
2398 another one (which might share some subprojects) rooted at B.
2400 Using only @command{gprbuild}, you could do
2407 to build both. But again, @command{gprbuild} has to do some duplicate work for
2408 those files that are shared between the two, and cannot truly build
2409 things in parallel efficiently.
2411 If the two projects are really independent, share no sources other
2412 than through a common subproject, and have no source files with a
2413 common basename, you could create a project C that imports A and
2414 B. But these restrictions are often too strong, and one has to build
2415 them independently. An aggregate project does not have these
2416 limitations and can aggregate two project trees that have common
2419 This scenario is particularly useful in environments like VxWorks 653
2420 where the applications running in the multiple partitions can be built
2421 in parallel through a single @command{gprbuild} command. This also works nicely
2424 @c ---------------------------------------------
2425 @node Define a build environment
2426 @subsection Define a build environment
2427 @c ---------------------------------------------
2429 The environment variables at the time you launch @command{gprbuild}
2430 will influence the view these tools have of the project
2431 (PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
2432 projects, environment variables that are referenced in project files
2433 through the "external" statement,...). Several command line switches
2434 can be used to override those (-X or -aP), but on some systems and
2435 with some projects, this might make the command line too long, and on
2436 all systems often make it hard to read.
2438 An aggregate project can be used to set the environment for all
2439 projects built through that aggregate. One of the nice aspects is that
2440 you can put the aggregate project under configuration management, and
2441 make sure all your user have a consistent environment when
2442 building. The syntax looks like
2444 @smallexample @c projectfile
2445 aggregate project Agg is
2446 for Project_Files use ("A.gpr", "B.gpr");
2447 for Project_Path use ("../dir1", "../dir1/dir2");
2448 for External ("BUILD") use "PRODUCTION";
2451 for ^Switches^Switches^ ("Ada") use ("-q");
2456 One of the often requested features in projects is to be able to
2457 reference external variables in @code{with} statements, as in
2459 @smallexample @c projectfile
2460 with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
2461 project MyProject is
2466 For various reasons, this isn't authorized. But using aggregate
2467 projects provide an elegant solution. For instance, you could
2468 use a project file like:
2470 @smallexample @c projectfile
2471 aggregate project Agg is
2472 for Project_Path use (external("SETUP") & "path");
2473 for Project_Files use ("myproject.gpr");
2476 with "prj.gpr"; -- searched on Agg'Project_Path
2477 project MyProject is
2482 @c --------------------------------------------
2483 @node Performance improvements in builder
2484 @subsection Performance improvements in builder
2485 @c --------------------------------------------
2487 The loading of aggregate projects is optimized in @command{gprbuild},
2488 so that all files are searched for only once on the disk
2489 (thus reducing the number of system calls and contributing to faster
2490 compilation times especially on systems with sources on remote
2491 servers). As part of the loading, @command{gprbuild}
2492 computes how and where a source file should be compiled, and even if it is
2493 found several times in the aggregated projects it will be compiled only
2496 Since there is no ambiguity as to which switches should be used, files
2497 can be compiled in parallel (through the usual -j switch) and this can
2498 be done while maximizing the use of CPUs (compared to launching
2499 multiple @command{gprbuild} and @command{gnatmake} commands in parallel).
2501 @c -------------------------------------
2502 @node Syntax of aggregate projects
2503 @subsection Syntax of aggregate projects
2504 @c -------------------------------------
2506 An aggregate project follows the general syntax of project files. The
2507 recommended extension is still @file{.gpr}. However, a special
2508 @code{aggregate} qualifier must be put before the keyword
2511 An aggregate project cannot @code{with} any other project (standard or
2512 aggregate), except an abstract project which can be used to share attribute
2513 values. Also, aggregate projects cannot be extended or imported though a
2514 @code{with} clause by any other project. Building other aggregate projects from
2515 an aggregate project is done through the Project_Files attribute (see below).
2517 An aggregate project does not have any source files directly (only
2518 through other standard projects). Therefore a number of the standard
2519 attributes and packages are forbidden in an aggregate project. Here is the
2520 (non exhaustive) list:
2524 @item Source_Files, Source_List_File and other attributes dealing with
2526 @item Source_Dirs, Exec_Dir and Object_Dir
2527 @item Library_Dir, Library_Name and other library-related attributes
2530 @item Externally_Built
2531 @item Inherit_Source_Path
2532 @item Excluded_Source_Dirs
2533 @item Locally_Removed_Files
2534 @item Excluded_Source_Files
2535 @item Excluded_Source_List_File
2539 The only package that is authorized (albeit optional) is
2540 Builder. Other packages (in particular Compiler, Binder and Linker)
2541 are forbidden. It is an error to have any of these
2542 (and such an error prevents the proper loading of the aggregate
2545 Three new attributes have been created, which can only be used in the
2546 context of aggregate projects:
2549 @item @b{Project_Files}:
2550 @cindex @code{Project_Files}
2552 This attribute is compulsory (or else we are not aggregating any project,
2553 and thus not doing anything). It specifies a list of @file{.gpr} files
2554 that are grouped in the aggregate. The list may be empty. The project
2555 files can be either other aggregate projects, or standard projects. When
2556 grouping standard projects, you can have both the root of a project tree
2557 (and you do not need to specify all its imported projects), and any project
2560 Basically, the idea is to specify all those projects that have
2561 main programs you want to build and link, or libraries you want to
2562 build. You can even specify projects that do not use the Main
2563 attribute nor the @code{Library_*} attributes, and the result will be to
2564 build all their source files (not just the ones needed by other
2567 The file can include paths (absolute or relative). Paths are relative to
2568 the location of the aggregate project file itself (if you use a base name,
2569 we expect to find the .gpr file in the same directory as the aggregate
2570 project file). The environment variables @code{ADA_PROJECT_PATH},
2571 @code{GPR_PROJECT_PATH} and @code{GPR_PROJECT_PATH_FILE} are not used to find
2572 the project files. The extension @file{.gpr} is mandatory, since this attribute
2573 contains file names, not project names.
2575 Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
2576 latter indicates that any subdirectory (recursively) will be
2577 searched for matching files. The latter (@code{"**"}) can only occur at the
2578 last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
2579 not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
2580 to starting with @code{"./**"}.
2582 For now, the pattern @code{"*"} is only allowed in the filename part, not
2583 in the directory part. This is mostly for efficiency reasons to limit the
2584 number of system calls that are needed.
2586 Here are a few valid examples:
2588 @smallexample @c projectfile
2589 for Project_Files use ("a.gpr", "subdir/b.gpr");
2590 -- two specific projects relative to the directory of agg.gpr
2592 for Project_Files use ("**/*.gpr");
2593 -- all projects recursively
2596 @item @b{Project_Path}:
2597 @cindex @code{Project_Path}
2599 This attribute can be used to specify a list of directories in
2600 which to look for project files in @code{with} statements.
2602 When you specify a project in Project_Files
2603 say @code{"x/y/a.gpr"}), and this projects imports a project "b.gpr", only
2604 b.gpr is searched in the project path. a.gpr must be exactly at
2605 <dir of the aggregate>/x/y/a.gpr.
2607 This attribute, however, does not affect the search for the aggregated
2608 project files specified with @code{Project_Files}.
2610 Each aggregate project has its own (that is if agg1.gpr includes
2611 agg2.gpr, they can potentially both have a different project path).
2613 This project path is defined as the concatenation, in that order, of:
2616 @item the current directory;
2617 @item followed by the command line -aP switches;
2618 @item then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment
2620 @item then the directories from the Project_Path attribute;
2621 @item and finally the predefined directories.
2624 In the example above, agg2.gpr's project path is not influenced by
2625 the attribute agg1'Project_Path, nor is agg1 influenced by
2628 This can potentially lead to errors. In the following example:
2631 +---------------+ +----------------+
2632 | Agg1.gpr |-=--includes--=-->| Agg2.gpr |
2633 | 'project_path| | 'project_path |
2635 +---------------+ +----------------+
2640 +-------+ +---------+
2641 | P.gpr |<---------- withs --------| Q.gpr |
2642 +-------+---------\ +---------+
2647 +-------+ +---------+
2648 | R.gpr | | R'.gpr |
2649 +-------+ +---------+
2652 When looking for p.gpr, both aggregates find the same physical file on
2653 the disk. However, it might happen that with their different project
2654 paths, both aggregate projects would in fact find a different r.gpr.
2655 Since we have a common project (p.gpr) "with"ing two different r.gpr,
2656 this will be reported as an error by the builder.
2658 Directories are relative to the location of the aggregate project file.
2660 Here are a few valid examples:
2662 @smallexample @c projectfile
2663 for Project_Path use ("/usr/local/gpr", "gpr/");
2667 @cindex @code{External}
2669 This attribute can be used to set the value of environment
2670 variables as retrieved through the @code{external} statement
2671 in projects. It does not affect the environment variables
2672 themselves (so for instance you cannot use it to change the value
2673 of your PATH as seen from the spawned compiler).
2675 This attribute affects the external values as seen in the rest of
2676 the aggreate projects, and in the aggregated projects.
2678 The exact value of external a variable comes from one of three
2679 sources (each level overrides the previous levels):
2682 @item An External attribute in aggregate project, for instance
2683 @code{for External ("BUILD_MODE") use "DEBUG"};
2685 @item Environment variables
2687 These override the value given by the attribute, so that
2688 users can override the value set in the (presumably shared
2689 with others in his team) aggregate project.
2691 @item The -X command line switch to @command{gprbuild}
2693 This always takes precedence.
2697 This attribute is only taken into account in the main aggregate
2698 project (i.e. the one specified on the command line to @command{gprbuild}),
2699 and ignored in other aggregate projects. It is invalid
2700 in standard projects.
2701 The goal is to have a consistent value in all
2702 projects that are built through the aggregate, which would not
2703 be the case in the diamond case: A groups the aggregate
2704 projects B and C, which both (either directly or indirectly)
2705 build the project P. If B and C could set different values for
2706 the environment variables, we would have two different views of
2707 P, which in particular might impact the list of source files in P.
2711 @c ----------------------------------------------
2712 @node package Builder in aggregate projects
2713 @subsection package Builder in aggregate projects
2714 @c ----------------------------------------------
2716 As we mentioned before, only the package Builder can be specified in
2717 an aggregate project. In this package, only the following attributes
2721 @item @b{^Switches^Switches^}:
2722 @cindex @code{^Switches^Switches^}
2723 This attribute gives the list of switches to use for @command{gprbuild}.
2724 Because no mains can be specified for aggregate projects, the only possible
2725 index for attribute @code{Switches} is @code{others}. All other indexes will
2730 @smallexample @c projectfile
2731 for ^Switches^Switches^ (others) use ("-v", "-k", "-j8");
2734 These switches are only read from the main aggregate project (the
2735 one passed on the command line), and ignored in all other aggregate
2736 projects or projects.
2738 It can only contain builder switches, not compiler switches.
2740 @item @b{Global_Compilation_Switches}
2741 @cindex @code{Global_Compilation_Switches}
2743 This attribute gives the list of compiler switches for the various
2744 languages. For instance,
2746 @smallexample @c projectfile
2747 for Global_Compilation_Switches ("Ada") use ("^O1^-O1^", "-g");
2748 for Global_Compilation_Switches ("C") use ("^-O2^-O2^");
2751 This attribute is only taken into account in the aggregate project
2752 specified on the command line, not in other aggregate projects.
2754 In the projects grouped by that aggregate, the attribute
2755 Builder.Global_Compilation_Switches is also ignored. However, the
2756 attribute Compiler.Default_Switches will be taken into account (but
2757 that of the aggregate have higher priority). The attribute
2758 Compiler.Switches is also taken into account and can be used to
2759 override the switches for a specific file. As a result, it always
2762 The rules are meant to avoid ambiguities when compiling. For
2763 instance, aggregate project Agg groups the projects A and B, that
2764 both depend on C. Here is an extra for all of these projects:
2766 @smallexample @c projectfile
2767 aggregate project Agg is
2768 for Project_Files use ("a.gpr", "b.gpr");
2770 for Global_Compilation_Switches ("Ada") use ("^-O2^-O2^");
2777 for Global_Compilation_Switches ("Ada") use ("^-O1^-O1^");
2782 for Default_Switches ("Ada")
2783 use ("^-O1^-O1^", "-g");
2784 for ^Switches^Switches^ ("a_file1.adb")
2792 for Default_Switches ("Ada") use ("^-O0^-O0^");
2798 for Default_Switches ("Ada")
2801 for ^Switches^Switches^ ("c_file1.adb")
2802 use ("^-O0^-O0^", "-g");
2807 then the following switches are used:
2810 @item all files from project A except a_file1.adb are compiled
2811 with "^-O2^-O2^ -g", since the aggregate project has priority.
2812 @item the file a_file1.adb is compiled with
2813 "^-O0^-O0^", since the Compiler.Switches has priority
2814 @item all files from project B are compiled with
2815 "^-O2^-O2^", since the aggregate project has priority
2816 @item all files from C are compiled with "^-O2^-O2^ -gnatn", except for
2817 c_file1.adb which is compiled with "^-O0^-O0^ -g"
2820 Even though C is seen through two paths (through A and through
2821 B), the switches used by the compiler are unambiguous.
2823 @item @b{Global_Configuration_Pragmas}
2824 @cindex @code{Global_Configuration_Pragmas}
2826 This attribute can be used to specify a file containing
2827 configuration pragmas, to be passed to the Ada compiler. Since we
2828 ignore the package Builder in other aggregate projects and projects,
2829 only those pragmas defined in the main aggregate project will be
2832 Projects can locally add to those by using the
2833 @code{Compiler.Local_Configuration_Pragmas} attribute if they need.
2835 @item @b{Global_Config_File}
2836 @cindex @code{Global_Config_File}
2838 This attribute, indexed with a language name, can be used to specify a config
2839 when compiling sources of the language. For Ada, these files are configuration
2844 For projects that are built through the aggregate, the package Builder
2845 is ignored, except for the Executable attribute which specifies the
2846 name of the executables resulting from the link of the main programs, and
2847 for the Executable_Suffix.
2849 @c ---------------------------------------------
2850 @node Aggregate Library Projects
2851 @section Aggregate Library Projects
2852 @c ---------------------------------------------
2856 Aggregate library projects make it possible to build a single library
2857 using object files built using other standard or library
2858 projects. This gives the flexibility to describe an application as
2859 having multiple modules (a GUI, database access, ...) using different
2860 project files (so possibly built with different compiler options) and
2861 yet create a single library (static or relocatable) out of the
2862 corresponding object files.
2865 * Building aggregate library projects::
2866 * Syntax of aggregate library projects::
2869 @c ---------------------------------------------
2870 @node Building aggregate library projects
2871 @subsection Building aggregate library projects
2872 @c ---------------------------------------------
2874 For example, we can define an aggregate project Agg that groups A, B
2877 @smallexample @c projectfile
2878 aggregate library project Agg is
2879 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2880 for Library_Name use ("agg");
2881 for Library_Dir use ("lagg");
2885 Then, when you build with:
2891 This will build all units from projects A, B and C and will create a
2892 static library named @file{libagg.a} into the @file{lagg}
2893 directory. An aggregate library project has the same set of
2894 restriction as a standard library project.
2896 Note that a shared aggregate library project cannot aggregate a
2897 static library project. In platforms where a compiler option is
2898 required to create relocatable object files, a Builder package in the
2899 aggregate library project may be used:
2901 @smallexample @c projectfile
2902 aggregate library project Agg is
2903 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2904 for Library_Name use ("agg");
2905 for Library_Dir use ("lagg");
2906 for Library_Kind use "relocatable";
2909 for Global_Compilation_Switches ("Ada") use ("-fPIC");
2914 With the above aggregate library Builder package, the @code{-fPIC}
2915 option will be passed to the compiler when building any source code
2916 from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}.
2918 @c ---------------------------------------------
2919 @node Syntax of aggregate library projects
2920 @subsection Syntax of aggregate library projects
2921 @c ---------------------------------------------
2923 An aggregate library project follows the general syntax of project
2924 files. The recommended extension is still @file{.gpr}. However, a special
2925 @code{aggregate library} qualifier must be put before the keyword
2928 An aggregate library project cannot @code{with} any other project
2929 (standard or aggregate), except an abstract project which can be used
2930 to share attribute values.
2932 An aggregate library project does not have any source files directly (only
2933 through other standard projects). Therefore a number of the standard
2934 attributes and packages are forbidden in an aggregate library
2935 project. Here is the (non exhaustive) list:
2939 @item Source_Files, Source_List_File and other attributes dealing with
2941 @item Source_Dirs, Exec_Dir and Object_Dir
2944 @item Externally_Built
2945 @item Inherit_Source_Path
2946 @item Excluded_Source_Dirs
2947 @item Locally_Removed_Files
2948 @item Excluded_Source_Files
2949 @item Excluded_Source_List_File
2953 The only package that is authorized (albeit optional) is Builder.
2955 The Project_Files attribute (See @pxref{Aggregate Projects}) is used to
2956 described the aggregated projects whose object files have to be
2957 included into the aggregate library. The environment variables
2958 @code{ADA_PROJECT_PATH}, @code{GPR_PROJECT_PATH} and
2959 @code{GPR_PROJECT_PATH_FILE} are not used to find the project files.
2961 @c ---------------------------------------------
2962 @node Project File Reference
2963 @section Project File Reference
2964 @c ---------------------------------------------
2967 This section describes the syntactic structure of project files, the various
2968 constructs that can be used. Finally, it ends with a summary of all available
2972 * Project Declaration::
2973 * Qualified Projects::
2978 * Typed String Declaration::
2980 * Case Constructions::
2984 @c ---------------------------------------------
2985 @node Project Declaration
2986 @subsection Project Declaration
2987 @c ---------------------------------------------
2990 Project files have an Ada-like syntax. The minimal project file is:
2992 @smallexample @c projectfile
3000 The identifier @code{Empty} is the name of the project.
3001 This project name must be present after the reserved
3002 word @code{end} at the end of the project file, followed by a semi-colon.
3004 @b{Identifiers} (i.e.@: the user-defined names such as project or variable names)
3005 have the same syntax as Ada identifiers: they must start with a letter,
3006 and be followed by zero or more letters, digits or underscore characters;
3007 it is also illegal to have two underscores next to each other. Identifiers
3008 are always case-insensitive ("Name" is the same as "name").
3011 simple_name ::= identifier
3012 name ::= simple_name @{ . simple_name @}
3016 @b{Strings} are used for values of attributes or as indexes for these
3017 attributes. They are in general case sensitive, except when noted
3018 otherwise (in particular, strings representing file names will be case
3019 insensitive on some systems, so that "file.adb" and "File.adb" both
3020 represent the same file).
3022 @b{Reserved words} are the same as for standard Ada 95, and cannot
3023 be used for identifiers. In particular, the following words are currently
3024 used in project files, but others could be added later on. In bold are the
3025 extra reserved words in project files: @code{all, at, case, end, for, is,
3026 limited, null, others, package, renames, type, use, when, with, @b{extends},
3027 @b{external}, @b{project}}.
3029 @b{Comments} in project files have the same syntax as in Ada, two consecutive
3030 hyphens through the end of the line.
3032 A project may be an @b{independent project}, entirely defined by a single
3033 project file. Any source file in an independent project depends only
3034 on the predefined library and other source files in the same project.
3035 But a project may also depend on other projects, either by importing them
3036 through @b{with clauses}, or by @b{extending} at most one other project. Both
3037 types of dependency can be used in the same project.
3039 A path name denotes a project file. It can be absolute or relative.
3040 An absolute path name includes a sequence of directories, in the syntax of
3041 the host operating system, that identifies uniquely the project file in the
3042 file system. A relative path name identifies the project file, relative
3043 to the directory that contains the current project, or relative to a
3044 directory listed in the environment variables ADA_PROJECT_PATH and
3045 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
3046 operating system are case sensitive. As a special case, the directory
3047 separator can always be "/" even on Windows systems, so that project files
3048 can be made portable across architectures.
3049 The syntax of the environment variable ADA_PROJECT_PATH and
3050 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
3051 semicolons on Windows.
3053 A given project name can appear only once in a context clause.
3055 It is illegal for a project imported by a context clause to refer, directly
3056 or indirectly, to the project in which this context clause appears (the
3057 dependency graph cannot contain cycles), except when one of the with clause
3058 in the cycle is a @b{limited with}.
3059 @c ??? Need more details here
3061 @smallexample @c projectfile
3062 with "other_project.gpr";
3063 project My_Project extends "extended.gpr" is
3068 These dependencies form a @b{directed graph}, potentially cyclic when using
3069 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
3072 A project's @b{immediate sources} are the source files directly defined by
3073 that project, either implicitly by residing in the project source directories,
3074 or explicitly through any of the source-related attributes.
3075 More generally, a project sources are the immediate sources of the project
3076 together with the immediate sources (unless overridden) of any
3077 project on which it depends directly or indirectly.
3079 A @b{project hierarchy} can be created, where projects are children of
3080 other projects. The name of such a child project must be @code{Parent.Child},
3081 where @code{Parent} is the name of the parent project. In particular, this
3082 makes all @code{with} clauses of the parent project automatically visible
3083 in the child project.
3086 project ::= context_clause project_declaration
3088 context_clause ::= @{with_clause@}
3089 with_clause ::= @i{with} path_name @{ , path_name @} ;
3090 path_name ::= string_literal
3092 project_declaration ::= simple_project_declaration | project_extension
3093 simple_project_declaration ::=
3094 @i{project} @i{<project_>}name @i{is}
3095 @{declarative_item@}
3096 @i{end} <project_>simple_name;
3099 @c ---------------------------------------------
3100 @node Qualified Projects
3101 @subsection Qualified Projects
3102 @c ---------------------------------------------
3105 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
3106 is identifiers or reserved words, to qualify the project.
3107 The current list of qualifiers is:
3110 @item @b{abstract}: qualifies a project with no sources. Such a
3111 project must either have no declaration of attributes @code{Source_Dirs},
3112 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
3113 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
3114 as empty. If it extends another project, the project it extends must also be a
3115 qualified abstract project.
3116 @item @b{standard}: a standard project is a non library project with sources.
3117 This is the default (implicit) qualifier.
3118 @item @b{aggregate}: a project whose sources are aggregated from other
3120 @item @b{aggregate library}: a library whose sources are aggregated
3121 from other project or library project files.
3122 @item @b{library}: a library project must declare both attributes
3123 @code{Library_Name} and @code{Library_Dir}.
3124 @item @b{configuration}: a configuration project cannot be in a project tree.
3125 It describes compilers and other tools to @command{gprbuild}.
3128 @c ---------------------------------------------
3130 @subsection Declarations
3131 @c ---------------------------------------------
3134 Declarations introduce new entities that denote types, variables, attributes,
3135 and packages. Some declarations can only appear immediately within a project
3136 declaration. Others can appear within a project or within a package.
3139 declarative_item ::= simple_declarative_item
3140 | typed_string_declaration
3141 | package_declaration
3143 simple_declarative_item ::= variable_declaration
3144 | typed_variable_declaration
3145 | attribute_declaration
3149 empty_declaration ::= @i{null} ;
3153 An empty declaration is allowed anywhere a declaration is allowed. It has
3156 @c ---------------------------------------------
3158 @subsection Packages
3159 @c ---------------------------------------------
3162 A project file may contain @b{packages}, that group attributes (typically
3163 all the attributes that are used by one of the GNAT tools).
3165 A package with a given name may only appear once in a project file.
3166 The following packages are currently supported in project files
3167 (See @pxref{Attributes} for the list of attributes that each can contain).
3171 This package specifies characteristics useful when invoking the binder either
3172 directly via the @command{gnat} driver or when using a builder such as
3173 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
3175 This package specifies the compilation options used when building an
3176 executable or a library for a project. Most of the options should be
3177 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
3178 but there are some general options that should be defined in this
3179 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
3183 This package specifies the options used when calling the checking tool
3184 @command{gnatcheck} via the @command{gnat} driver. Its attribute
3185 @b{Default_Switches} has the same semantics as for the package
3186 @code{Builder}. The first string should always be @code{-rules} to specify
3187 that all the other options belong to the @code{-rules} section of the
3188 parameters to @command{gnatcheck}.
3191 This package specifies the options used when cleaning a project or a project
3192 tree using the tools @command{gnatclean} or @command{gprclean}.
3194 This package specifies the compilation options used by the compiler for
3195 each languages. @xref{Tools Options in Project Files}.
3196 @item Cross_Reference
3197 This package specifies the options used when calling the library tool
3198 @command{gnatxref} via the @command{gnat} driver. Its attributes
3199 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3200 package @code{Builder}.
3203 This package specifies the options used when calling the tool
3204 @command{gnatelim} via the @command{gnat} driver. Its attributes
3205 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3206 package @code{Builder}.
3209 This package specifies the options used when calling the search tool
3210 @command{gnatfind} via the @command{gnat} driver. Its attributes
3211 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3212 package @code{Builder}.
3213 @item ^Gnatls^Gnatls^
3214 This package specifies the options to use when invoking @command{gnatls}
3215 via the @command{gnat} driver.
3217 @item ^Gnatstub^Gnatstub^
3218 This package specifies the options used when calling the tool
3219 @command{gnatstub} via the @command{gnat} driver. Its attributes
3220 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3221 package @code{Builder}.
3224 This package specifies the options used when starting an integrated
3225 development environment, for instance @command{GPS} or @command{Gnatbench}.
3227 This package specifies the options used when installing a project
3228 with @command{gprinstall}. @xref{Installation}.
3230 This package specifies the options used by the linker.
3231 @xref{Main Subprograms}.
3234 This package specifies the options used when calling the tool
3235 @command{gnatmetric} via the @command{gnat} driver. Its attributes
3236 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3237 package @code{Builder}.
3240 This package specifies the naming conventions that apply
3241 to the source files in a project. In particular, these conventions are
3242 used to automatically find all source files in the source directories,
3243 or given a file name to find out its language for proper processing.
3244 @xref{Naming Schemes}.
3246 @item Pretty_Printer
3247 This package specifies the options used when calling the formatting tool
3248 @command{gnatpp} via the @command{gnat} driver. Its attributes
3249 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3250 package @code{Builder}.
3253 This package is used by @command{gprbuild} to describe how distributed
3254 compilation should be done.
3256 This package specifies the options used when calling the tool
3257 @command{gnatstack} via the @command{gnat} driver. Its attributes
3258 @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
3259 package @code{Builder}.
3261 This package specifies the options used when calling the tool
3262 @command{gnatsync} via the @command{gnat} driver.
3266 In its simplest form, a package may be empty:
3268 @smallexample @c projectfile
3278 A package may contain @b{attribute declarations},
3279 @b{variable declarations} and @b{case constructions}, as will be
3282 When there is ambiguity between a project name and a package name,
3283 the name always designates the project. To avoid possible confusion, it is
3284 always a good idea to avoid naming a project with one of the
3285 names allowed for packages or any name that starts with @code{gnat}.
3287 A package can also be defined by a @b{renaming declaration}. The new package
3288 renames a package declared in a different project file, and has the same
3289 attributes as the package it renames. The name of the renamed package
3290 must be the same as the name of the renaming package. The project must
3291 contain a package declaration with this name, and the project
3292 must appear in the context clause of the current project, or be its parent
3293 project. It is not possible to add or override attributes to the renaming
3294 project. If you need to do so, you should use an @b{extending declaration}
3297 Packages that are renamed in other project files often come from project files
3298 that have no sources: they are just used as templates. Any modification in the
3299 template will be reflected automatically in all the project files that rename
3300 a package from the template. This is a very common way to share settings
3303 Finally, a package can also be defined by an @b{extending declaration}. This is
3304 similar to a @b{renaming declaration}, except that it is possible to add or
3305 override attributes.
3308 package_declaration ::= package_spec | package_renaming | package_extension
3310 @i{package} @i{<package_>}simple_name @i{is}
3311 @{simple_declarative_item@}
3312 @i{end} package_identifier ;
3313 package_renaming ::==
3314 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
3315 package_extension ::==
3316 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
3317 @{simple_declarative_item@}
3318 @i{end} package_identifier ;
3321 @c ---------------------------------------------
3323 @subsection Expressions
3324 @c ---------------------------------------------
3327 An expression is any value that can be assigned to an attribute or a
3328 variable. It is either a literal value, or a construct requiring runtime
3329 computation by the project manager. In a project file, the computed value of
3330 an expression is either a string or a list of strings.
3332 A string value is one of:
3334 @item A literal string, for instance @code{"comm/my_proj.gpr"}
3335 @item The name of a variable that evaluates to a string (@pxref{Variables})
3336 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
3337 @item An external reference (@pxref{External Values})
3338 @item A concatenation of the above, as in @code{"prefix_" & Var}.
3343 A list of strings is one of the following:
3346 @item A parenthesized comma-separated list of zero or more string expressions, for
3347 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
3348 @item The name of a variable that evaluates to a list of strings
3349 @item The name of an attribute that evaluates to a list of strings
3350 @item A concatenation of a list of strings and a string (as defined above), for
3351 instance @code{("A", "B") & "C"}
3352 @item A concatenation of two lists of strings
3357 The following is the grammar for expressions
3360 string_literal ::= "@{string_element@}" -- Same as Ada
3361 string_expression ::= string_literal
3364 | attribute_reference
3365 | ( string_expression @{ & string_expression @} )
3366 string_list ::= ( string_expression @{ , string_expression @} )
3367 | @i{string_variable}_name
3368 | @i{string_}attribute_reference
3369 term ::= string_expression | string_list
3370 expression ::= term @{ & term @} -- Concatenation
3374 Concatenation involves strings and list of strings. As soon as a list of
3375 strings is involved, the result of the concatenation is a list of strings. The
3376 following Ada declarations show the existing operators:
3378 @smallexample @c ada
3379 function "&" (X : String; Y : String) return String;
3380 function "&" (X : String_List; Y : String) return String_List;
3381 function "&" (X : String_List; Y : String_List) return String_List;
3385 Here are some specific examples:
3387 @smallexample @c projectfile
3389 List := () & File_Name; -- One string in this list
3390 List2 := List & (File_Name & ".orig"); -- Two strings
3391 Big_List := List & Lists2; -- Three strings
3392 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
3396 @c ---------------------------------------------
3397 @node External Values
3398 @subsection External Values
3399 @c ---------------------------------------------
3402 An external value is an expression whose value is obtained from the command
3403 that invoked the processing of the current project file (typically a
3404 @command{gnatmake} or @command{gprbuild} command).
3406 There are two kinds of external values, one that returns a single string, and
3407 one that returns a string list.
3409 The syntax of a single string external value is:
3412 external_value ::= @i{external} ( string_literal [, string_literal] )
3416 The first string_literal is the string to be used on the command line or
3417 in the environment to specify the external value. The second string_literal,
3418 if present, is the default to use if there is no specification for this
3419 external value either on the command line or in the environment.
3421 Typically, the external value will either exist in the
3422 ^environment variables^logical name^
3423 or be specified on the command line through the
3424 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
3425 are specified, then the command line value is used, so that a user can more
3426 easily override the value.
3428 The function @code{external} always returns a string. It is an error if the
3429 value was not found in the environment and no default was specified in the
3430 call to @code{external}.
3432 An external reference may be part of a string expression or of a string
3433 list expression, and can therefore appear in a variable declaration or
3434 an attribute declaration.
3436 Most of the time, this construct is used to initialize typed variables, which
3437 are then used in @b{case} statements to control the value assigned to
3438 attributes in various scenarios. Thus such variables are often called
3439 @b{scenario variables}.
3441 The syntax for a string list external value is:
3444 external_value ::= @i{external_as_list} ( string_literal , string_literal )
3448 The first string_literal is the string to be used on the command line or
3449 in the environment to specify the external value. The second string_literal is
3450 the separator between each component of the string list.
3452 If the external value does not exist in the environment or on the command line,
3453 the result is an empty list. This is also the case, if the separator is an
3454 empty string or if the external value is only one separator.
3456 Any separator at the beginning or at the end of the external value is
3457 discarded. Then, if there is no separator in the external value, the result is
3458 a string list with only one string. Otherwise, any string between the beginning
3459 and the first separator, between two consecutive separators and between the
3460 last separator and the end are components of the string list.
3463 @i{external_as_list} ("SWITCHES", ",")
3467 If the external value is "^-O2^-O2^,-g",
3468 the result is ("^-O2^-O2^", "-g").
3470 If the external value is ",^-O2^-O2^,-g,",
3471 the result is also ("^-O2^-O2^", "-g").
3473 if the external value is "^-gnatv^-gnatv^",
3474 the result is ("^-gnatv^-gnatv^").
3476 If the external value is ",,", the result is ("").
3478 If the external value is ",", the result is (), the empty string list.
3480 @c ---------------------------------------------
3481 @node Typed String Declaration
3482 @subsection Typed String Declaration
3483 @c ---------------------------------------------
3486 A @b{type declaration} introduces a discrete set of string literals.
3487 If a string variable is declared to have this type, its value
3488 is restricted to the given set of literals. These are the only named
3489 types in project files. A string type may only be declared at the project
3490 level, not inside a package.
3493 typed_string_declaration ::=
3494 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
3498 The string literals in the list are case sensitive and must all be different.
3499 They may include any graphic characters allowed in Ada, including spaces.
3500 Here is an example of a string type declaration:
3502 @smallexample @c projectfile
3503 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
3507 Variables of a string type are called @b{typed variables}; all other
3508 variables are called @b{untyped variables}. Typed variables are
3509 particularly useful in @code{case} constructions, to support conditional
3510 attribute declarations. (@pxref{Case Constructions}).
3512 A string type may be referenced by its name if it has been declared in the same
3513 project file, or by an expanded name whose prefix is the name of the project
3514 in which it is declared.
3516 @c ---------------------------------------------
3518 @subsection Variables
3519 @c ---------------------------------------------
3522 @b{Variables} store values (strings or list of strings) and can appear
3523 as part of an expression. The declaration of a variable creates the
3524 variable and assigns the value of the expression to it. The name of the
3525 variable is available immediately after the assignment symbol, if you
3526 need to reuse its old value to compute the new value. Before the completion
3527 of its first declaration, the value of a variable defaults to the empty
3530 A @b{typed} variable can be used as part of a @b{case} expression to
3531 compute the value, but it can only be declared once in the project file,
3532 so that all case constructions see the same value for the variable. This
3533 provides more consistency and makes the project easier to understand.
3534 The syntax for its declaration is identical to the Ada syntax for an
3535 object declaration. In effect, a typed variable acts as a constant.
3537 An @b{untyped} variable can be declared and overridden multiple times
3538 within the same project. It is declared implicitly through an Ada
3539 assignment. The first declaration establishes the kind of the variable
3540 (string or list of strings) and successive declarations must respect
3541 the initial kind. Assignments are executed in the order in which they
3542 appear, so the new value replaces the old one and any subsequent reference
3543 to the variable uses the new value.
3545 A variable may be declared at the project file level, or within a package.
3548 typed_variable_declaration ::=
3549 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
3550 variable_declaration ::= @i{<variable_>}simple_name := expression;
3554 Here are some examples of variable declarations:
3556 @smallexample @c projectfile
3558 This_OS : OS := external ("OS"); -- a typed variable declaration
3559 That_OS := "GNU/Linux"; -- an untyped variable declaration
3561 Name := "readme.txt";
3562 Save_Name := Name & ".saved";
3565 List_With_One_Element := ("-gnaty");
3566 List_With_Two_Elements := List_With_One_Element & "-gnatg";
3567 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
3572 A @b{variable reference} may take several forms:
3575 @item The simple variable name, for a variable in the current package (if any)
3576 or in the current project
3577 @item An expanded name, whose prefix is a context name.
3582 A @b{context} may be one of the following:
3585 @item The name of an existing package in the current project
3586 @item The name of an imported project of the current project
3587 @item The name of an ancestor project (i.e., a project extended by the current
3588 project, either directly or indirectly)
3589 @item An expanded name whose prefix is an imported/parent project name, and
3590 whose selector is a package name in that project.
3593 @c ---------------------------------------------
3594 @node Case Constructions
3595 @subsection Case Constructions
3596 @c ---------------------------------------------
3599 A @b{case} statement is used in a project file to effect conditional
3600 behavior. Through this statement, you can set the value of attributes
3601 and variables depending on the value previously assigned to a typed
3604 All choices in a choice list must be distinct. Unlike Ada, the choice
3605 lists of all alternatives do not need to include all values of the type.
3606 An @code{others} choice must appear last in the list of alternatives.
3608 The syntax of a @code{case} construction is based on the Ada case statement
3609 (although the @code{null} statement for empty alternatives is optional).
3611 The case expression must be a typed string variable, whose value is often
3612 given by an external reference (@pxref{External Values}).
3614 Each alternative starts with the reserved word @code{when}, either a list of
3615 literal strings separated by the @code{"|"} character or the reserved word
3616 @code{others}, and the @code{"=>"} token.
3617 Each literal string must belong to the string type that is the type of the
3619 After each @code{=>}, there are zero or more statements. The only
3620 statements allowed in a case construction are other case constructions,
3621 attribute declarations and variable declarations. String type declarations and
3622 package declarations are not allowed. Variable declarations are restricted to
3623 variables that have already been declared before the case construction.
3627 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
3630 @i{when} discrete_choice_list =>
3632 | attribute_declaration
3633 | variable_declaration
3634 | empty_declaration@}
3636 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
3640 Here is a typical example:
3642 @smallexample @c projectfile
3645 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
3646 OS : OS_Type := external ("OS", "GNU/Linux");
3650 when "GNU/Linux" | "Unix" =>
3651 for ^Switches^Switches^ ("Ada")
3654 for ^Switches^Switches^ ("Ada")
3655 use ("^-gnatP^-gnatP^");
3664 @c ---------------------------------------------
3666 @subsection Attributes
3667 @c ---------------------------------------------
3670 * Project Level Attributes::
3671 * Package Binder Attributes::
3672 * Package Builder Attributes::
3674 * Package Check Attributes::
3676 * Package Clean Attributes::
3677 * Package Compiler Attributes::
3678 * Package Cross_Reference Attributes::
3680 * Package Eliminate Attributes::
3682 * Package Finder Attributes::
3683 * Package ^gnatls^gnatls^ Attributes::
3685 * Package ^gnatstub^gnatstub^ Attributes::
3687 * Package IDE Attributes::
3688 * Package Install Attributes::
3689 * Package Linker Attributes::
3691 * Package Metrics Attribute::
3693 * Package Naming Attributes::
3695 * Package Pretty_Printer Attributes::
3697 * Package Remote Attributes::
3698 * Package Stack Attributes::
3699 * Package Synchronize Attributes::
3703 A project (and its packages) may have @b{attributes} that define
3704 the project's properties. Some attributes have values that are strings;
3705 others have values that are string lists.
3708 attribute_declaration ::=
3709 simple_attribute_declaration | indexed_attribute_declaration
3710 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
3711 indexed_attribute_declaration ::=
3712 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
3713 attribute_designator ::=
3714 @i{<simple_attribute_>}simple_name
3715 | @i{<indexed_attribute_>}simple_name ( string_literal )
3719 There are two categories of attributes: @b{simple attributes}
3720 and @b{indexed attributes}.
3721 Each simple attribute has a default value: the empty string (for string
3722 attributes) and the empty list (for string list attributes).
3723 An attribute declaration defines a new value for an attribute, and overrides
3724 the previous value. The syntax of a simple attribute declaration is similar to
3725 that of an attribute definition clause in Ada.
3727 Some attributes are indexed. These attributes are mappings whose
3728 domain is a set of strings. They are declared one association
3729 at a time, by specifying a point in the domain and the corresponding image
3731 Like untyped variables and simple attributes, indexed attributes
3732 may be declared several times. Each declaration supplies a new value for the
3733 attribute, and replaces the previous setting.
3735 Here are some examples of attribute declarations:
3737 @smallexample @c projectfile
3738 -- simple attributes
3739 for Object_Dir use "objects";
3740 for Source_Dirs use ("units", "test/drivers");
3742 -- indexed attributes
3743 for Body ("main") use "Main.ada";
3744 for ^Switches^Switches^ ("main.ada")
3745 use ("-v", "^-gnatv^-gnatv^");
3746 for ^Switches^Switches^ ("main.ada") use Builder'Switches ("main.ada") & "-g";
3748 -- indexed attributes copy (from package Builder in project Default)
3749 -- The package name must always be specified, even if it is the current
3751 for Default_Switches use Default.Builder'Default_Switches;
3755 Attributes references may appear anywhere in expressions, and are used
3756 to retrieve the value previously assigned to the attribute. If an attribute
3757 has not been set in a given package or project, its value defaults to the
3758 empty string or the empty list.
3761 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
3762 attribute_prefix ::= @i{project}
3763 | @i{<project_>}simple_name
3764 | package_identifier
3765 | @i{<project_>}simple_name . package_identifier
3771 @smallexample @c projectfile
3773 Naming'Dot_Replacement
3774 Imported_Project'Source_Dirs
3775 Imported_Project.Naming'Casing
3776 Builder'Default_Switches ("Ada")
3780 The prefix of an attribute may be:
3783 @item @code{project} for an attribute of the current project
3784 @item The name of an existing package of the current project
3785 @item The name of an imported project
3786 @item The name of a parent project that is extended by the current project
3787 @item An expanded name whose prefix is imported/parent project name,
3788 and whose selector is a package name
3794 In the following sections, all predefined attributes are succinctly described,
3795 first the project level attributes, that is those attributes that are not in a
3796 package, then the attributes in the different packages.
3798 It is possible for different tools to create dynamically new packages with
3799 attributes, or new attribute in predefined packages. These attributes are
3800 not documented here.
3802 The attributes under Configuration headings are usually found only in
3803 configuration project files.
3805 The characteristics of each attribute are indicated as follows:
3809 @item @b{Type of value}
3811 The value of an attribute may be a single string, indicated by the word
3812 "single", or a string list, indicated by the word "list".
3816 When the attribute is read-only, that is when it is not allowed to declare
3817 the attribute, this is indicated by the words "read-only".
3819 @item @b{Optional index}
3821 If it is allowed in the value of the attribute (both single and list) to have
3822 an optional index, this is indicated by the words "optional index".
3824 @item @b{Indexed attribute}
3826 When an it is an indexed attribute, this is indicated by the word "indexed".
3828 @item @b{Case-sensitivity of the index}
3830 For an indexed attribute, if the index is case-insensitive, this is indicated
3831 by the words "case-insensitive index".
3833 @item @b{File name index}
3835 For an indexed attribute, when the index is a file name, this is indicated by
3836 the words "file name index". The index may or may not be case-sensitive,
3837 depending on the platform.
3839 @item @b{others allowed in index}
3841 For an indexed attribute, if it is allowed to use @b{others} as the index,
3842 this is indicated by the words "others allowed".
3844 When @b{others} is used as the index of an indexed attribute, the value of
3845 the attribute indexed by @b{others} is used when no other index would apply.
3849 @node Project Level Attributes
3850 @subsubsection Project Level Attributes
3859 @item @b{Name}: single, read-only
3861 The name of the project.
3863 @item @b{Project_Dir}: single, read-only
3865 The path name of the project directory.
3867 @item @b{Main}: list, optional index
3869 The list of main sources for the executables.
3871 @item @b{Languages}: list
3873 The list of languages of the sources of the project.
3875 @item @b{Roots}: list, indexed, file name index
3877 The index is the file name of an executable source. Indicates the list of units
3878 from the main project that need to be bound and linked with their closures
3879 with the executable. The index is either a file name, a language name or "*".
3880 The roots for an executable source are those in @b{Roots} with an index that
3881 is the executable source file name, if declared. Otherwise, they are those in
3882 @b{Roots} with an index that is the language name of the executable source,
3883 if present. Otherwise, they are those in @b{Roots ("*")}, if declared. If none
3884 of these three possibilities are declared, then there are no roots for the
3887 @item @b{Externally_Built}: single
3889 Indicates if the project is externally built.
3890 Only case-insensitive values allowed are "true" and "false", the default.
3895 @item @b{Directories}
3899 @item @b{Object_Dir}: single
3901 Indicates the object directory for the project.
3903 @item @b{Exec_Dir}: single
3905 Indicates the exec directory for the project, that is the directory where the
3908 @item @b{Source_Dirs}: list
3910 The list of source directories of the project.
3912 @item @b{Inherit_Source_Path}: list, indexed, case-insensitive index
3914 Index is a language name. Value is a list of language names. Indicates that
3915 in the source search path of the index language the source directories of
3916 the languages in the list should be included.
3920 for Inherit_Source_Path ("C++") use ("C");
3922 @item @b{Exclude_Source_Dirs}: list
3924 The list of directories that are included in Source_Dirs but are not source
3925 directories of the project.
3927 @item @b{Ignore_Source_Sub_Dirs}: list
3929 Value is a list of simple names for subdirectories that are removed from the
3930 list of source directories, including theur subdirectories.
3934 @item @b{Source Files}
3938 @item @b{Source_Files}: list
3940 Value is a list of source file simple names.
3942 @item @b{Locally_Removed_Files}: list
3944 Obsolescent. Equivalent to Excluded_Source_Files.
3946 @item @b{Excluded_Source_Files}: list
3948 Value is a list of simple file names that are not sources of the project.
3949 Allows to remove sources that are inherited or found in the source directories
3950 and that match the naming scheme.
3952 @item @b{Source_List_File}: single
3954 Value is a text file name that contains a list of source file simple names,
3957 @item @b{Excluded_Source_List_File}: single
3959 Value is a text file name that contains a list of file simple names that
3960 are not sources of the project.
3962 @item @b{Interfaces}: list
3964 Value is a list of file names that constitutes the interfaces of the project.
3968 @item @b{Aggregate Projects}
3972 @item @b{Project_Files}: list
3974 Value is the list of aggregated projects.
3976 @item @b{Project_Path}: list
3978 Value is a list of directories that are added to the project search path when
3979 looking for the aggregated projects.
3981 @item @b{External}: single, indexed
3983 Index is the name of an external reference. Value is the value of the
3984 external reference to be used when parsing the aggregated projects.
3992 @item @b{Library_Dir}: single
3994 Value is the name of the library directory. This attribute needs to be
3995 declared for each library project.
3997 @item @b{Library_Name}: single
3999 Value is the name of the library. This attribute needs to be declared or
4000 inherited for each library project.
4002 @item @b{Library_Kind}: single
4004 Specifies the kind of library: static library (archive) or shared library.
4005 Case-insensitive values must be one of "static" for archives (the default) or
4006 "dynamic" or "relocatable" for shared libraries.
4008 @item @b{Library_Version}: single
4010 Value is the name of the library file.
4012 @item @b{Library_Interface}: list
4014 Value is the list of unit names that constitutes the interfaces
4015 of a Stand-Alone Library project.
4017 @item @b{Library_Standalone}: single
4019 Specifies if a Stand-Alone Library (SAL) is encapsulated or not.
4020 Only authorized case-insensitive values are "standard" for non encapsulated
4021 SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project.
4023 @item @b{Library_Encapsulated_Options}: list
4025 Value is a list of options that need to be used when linking an encapsulated
4026 Stand-Alone Library.
4028 @item @b{Library_Encapsulated_Supported}: single
4030 Indicates if encapsulated Stand-Alone Libraries are supported. Only
4031 authorized case-insensitive values are "true" and "false" (the default).
4033 @item @b{Library_Auto_Init}: single
4035 Indicates if a Stand-Alone Library is auto-initialized. Only authorized
4036 case-insentive values are "true" and "false".
4038 @item @b{Leading_Library_Options}: list
4040 Value is a list of options that are to be used at the beginning of
4041 the command line when linking a shared library.
4043 @item @b{Library_Options}: list
4045 Value is a list of options that are to be used when linking a shared library.
4047 @item @b{Library_Rpath_Options}: list, indexed, case-insensitive index
4049 Index is a language name. Value is a list of options for an invocation of the
4050 compiler of the language. This invocation is done for a shared library project
4051 with sources of the language. The output of the invocation is the path name
4052 of a shared library file. The directory name is to be put in the run path
4053 option switch when linking the shared library for the project.
4055 @item @b{Library_Src_Dir}: single
4057 Value is the name of the directory where copies of the sources of the
4058 interfaces of a Stand-Alone Library are to be copied.
4060 @item @b{Library_ALI_Dir}: single
4062 Value is the name of the directory where the ALI files of the interfaces
4063 of a Stand-Alone Library are to be copied. When this attribute is not declared,
4064 the directory is the library directory.
4066 @item @b{Library_gcc}: single
4068 Obsolescent attribute. Specify the linker driver used to link a shared library.
4069 Use instead attribute Linker'Driver.
4071 @item @b{Library_Symbol_File}: single
4073 Value is the name of the library symbol file.
4075 @item @b{Library_Symbol_Policy}: single
4077 Indicates the symbol policy kind. Only authorized case-insensitive values are
4078 "autonomous", "default", "compliant", "controlled" or "direct".
4080 @item @b{Library_Reference_Symbol_File}: single
4082 Value is the name of the reference symbol file.
4086 @item @b{Configuration - General}
4090 @item @b{Default_Language}: single
4092 Value is the case-insensitive name of the language of a project when attribute
4093 Languages is not specified.
4095 @item @b{Run_Path_Option}: list
4097 Value is the list of switches to be used when specifying the run path option
4100 @item @b{Run_Path_Origin}: single
4102 Value is the the string that may replace the path name of the executable
4103 directory in the run path options.
4105 @item @b{Separate_Run_Path_Options}: single
4107 Indicates if there may be or not several run path options specified when
4108 linking an executable. Only authorized case-insensitive b=values are "true" or
4109 "false" (the default).
4111 @item @b{Toolchain_Version}: single, indexed, case-insensitive index
4113 Index is a language name. Specify the version of a toolchain for a language.
4115 @item @b{Toolchain_Description}: single, indexed, case-insensitive index
4117 Obsolescent. No longer used.
4119 @item @b{Object_Generated}: single, indexed, case-insensitive index
4121 Index is a language name. Indicates if invoking the compiler for a language
4122 produces an object file. Only authorized case-insensitive values are "false"
4123 and "true" (the default).
4125 @item @b{Objects_Linked}: single, indexed, case-insensitive index
4127 Index is a language name. Indicates if the object files created by the compiler
4128 for a language need to be linked in the executable. Only authorized
4129 case-insensitive values are "false" and "true" (the default).
4131 @item @b{Target}: single
4133 Value is the name of the target platform.
4137 @item @b{Configuration - Libraries}
4141 @item @b{Library_Builder}: single
4143 Value is the path name of the application that is to be used to build
4144 libraries. Usually the path name of "gprlib".
4146 @item @b{Library_Support}: single
4148 Indicates the level of support of libraries. Only authorized case-insensitive
4149 values are "static_only", "full" or "none" (the default).
4153 @item @b{Configuration - Archives}
4157 @item @b{Archive_Builder}: list
4159 Value is the name of the application to be used to create a static library
4160 (archive), followed by the options to be used.
4162 @item @b{Archive_Builder_Append_Option}: list
4164 Value is the list of options to be used when invoking the archive builder
4165 to add project files into an archive.
4167 @item @b{Archive_Indexer}: list
4169 Value is the name of the archive indexer, followed by the required options.
4171 @item @b{Archive_Suffix}: single
4173 Value is the extension of archives. When not declared, the extension is ".a".
4175 @item @b{Library_Partial_Linker}: list
4177 Value is the name of the partial linker executable, followed by the required
4182 @item @b{Configuration - Shared Libraries}
4186 @item @b{Shared_Library_Prefix}: single
4188 Value is the prefix in the name of shared library files. When not declared,
4189 the prefix is "lib".
4191 @item @b{Shared_Library_Suffix}: single
4193 Value is the the extension of the name of shared library files. When not
4194 declared, the extension is ".so".
4196 @item @b{Symbolic_Link_Supported}: single
4198 Indicates if symbolic links are supported on the platform. Only authorized
4199 case-insensitive values are "true" and "false" (the default).
4201 @item @b{Library_Major_Minor_Id_Supported}: single
4203 Indicates if major and minor ids for shared library names are supported on
4204 the platform. Only authorized case-insensitive values are "true" and "false"
4207 @item @b{Library_Auto_Init_Supported}: single
4209 Indicates if auto-initialization of Stand-Alone Libraries is supported. Only
4210 authorized case-insensitive values are "true" and "false" (the default).
4212 @item @b{Shared_Library_Minimum_Switches}: list
4214 Value is the list of required switches when linking a shared library.
4216 @item @b{Library_Version_Switches}: list
4218 Value is the list of switches to specify a internal name for a shared library.
4220 @item @b{Library_Install_Name_Option}: single
4222 Value is the name of the option that needs to be used, concatenated with the
4223 path name of the library file, when linking a shared library.
4225 @item @b{Runtime_Library_Dir}: single, indexed, case-insensitive index
4227 Index is a language name. Value is the path name of the directory where the
4228 runtime libraries are located.
4230 @item @b{Runtime_Source_Dir}: single, indexed, case-insensitive index
4232 Index is a language name. Value is the path name of the directory where the
4233 sources of runtime libraries are located.
4239 @node Package Binder Attributes
4240 @subsubsection Package Binder Attributes
4248 @item @b{Default_Switches}: list, indexed, case-insensitive index
4250 Index is a language name. Value is the list of switches to be used when binding
4251 code of the language, if there is no applicable attribute ^Switches^Switches^.
4253 @item @b{^Switches^Switches^}: list, optional index, indexed,
4254 case-insensitive index, others allowed
4256 Index is either a language name or a source file name. Value is the list of
4257 switches to be used when binding code. Index is either the source file name
4258 of the executable to be bound or the language name of the code to be bound.
4262 @item @b{Configuration - Binding}
4266 @item @b{Driver}: single, indexed, case-insensitive index
4268 Index is a language name. Value is the name of the application to be used when
4269 binding code of the language.
4271 @item @b{Required_Switches}: list, indexed, case-insensitive index
4273 Index is a language name. Value is the list of the required switches to be
4274 used when binding code of the language.
4276 @item @b{Prefix}: single, indexed, case-insensitive index
4278 Index is a language name. Value is a prefix to be used for the binder exchange
4279 file name for the language. Used to have different binder exchange file names
4280 when binding different languages.
4282 @item @b{Objects_Path}: single,indexed, case-insensitive index
4284 Index is a language name. Value is the name of the environment variable that
4285 contains the path for the object directories.
4287 @item @b{Object_Path_File}: single,indexed, case-insensitive index
4289 Index is a language name. Value is the name of the environment variable. The
4290 value of the environment variable is the path name of a text file that
4291 contains the list of object directories.
4297 @node Package Builder Attributes
4298 @subsubsection Package Builder Attributes
4302 @item @b{Default_Switches}: list, indexed, case-insensitive index
4304 Index is a language name. Value is the list of builder switches to be used when
4305 building an executable of the language, if there is no applicable attribute
4308 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4311 Index is either a language name or a source file name. Value is the list of
4312 builder switches to be used when building an executable. Index is either the
4313 source file name of the executable to be built or its language name.
4315 @item @b{Global_Compilation_Switches}: list, optional index, indexed,
4316 case-insensitive index
4318 Index is either a language name or a source file name. Value is the list of
4319 compilation switches to be used when building an executable. Index is either
4320 the source file name of the executable to be built or its language name.
4322 @item @b{Executable}: single, indexed, case-insensitive index
4324 Index is an executable source file name. Value is the simple file name of the
4325 executable to be built.
4327 @item @b{Executable_Suffix}: single
4329 Value is the extension of the file names of executable. When not specified,
4330 the extension is the default extension of executables on the platform.
4332 @item @b{Global_Configuration_Pragmas}: single
4334 Value is the file name of a configuration pragmas file that is specified to
4335 the Ada compiler when compiling any Ada source in the project tree.
4337 @item @b{Global_Config_File}: single, indexed, case-insensitive index
4339 Index is a language name. Value is the file name of a configuration file that
4340 is specified to the compiler when compiling any source of the language in the
4346 @node Package Check Attributes
4347 @subsubsection Package Check Attributes
4351 @item @b{Default_Switches}: list, indexed, case-insensitive index
4353 Index is a language name. Value is a list of switches to be used when invoking
4354 @code{gnatcheck} for a source of the language, if there is no applicable
4355 attribute ^Switches^Switches^.
4357 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4360 Index is a source file name. Value is the list of switches to be used when
4361 invoking @code{gnatcheck} for the source.
4366 @node Package Clean Attributes
4367 @subsubsection Package Clean Attributes
4371 @item @b{^Switches^Switches^}: list
4373 Value is a list of switches to be used by the cleaning application.
4375 @item @b{Source_Artifact_Extensions}: list, indexed, case-insensitive index
4377 Index is a language names. Value is the list of extensions for file names
4378 derived from object file names that need to be cleaned in the object
4379 directory of the project.
4381 @item @b{Object_Artifact_Extensions}: list, indexed, case-insensitive index
4383 Index is a language names. Value is the list of extensions for file names
4384 derived from source file names that need to be cleaned in the object
4385 directory of the project.
4387 @item @b{Artifacts_In_Object_Dir}: single
4389 Value is a list of file names expressed as regular expressions that are to be
4390 deleted by gprclean in the object directory of the project.
4392 @item @b{Artifacts_In_Exec_Dir}: single
4394 Value is list of file names expressed as regular expressions that are to be
4395 deleted by gprclean in the exec directory of the main project.
4399 @node Package Compiler Attributes
4400 @subsubsection Package Compiler Attributes
4408 @item @b{Default_Switches}: list, indexed, case-insensitive index
4410 Index is a language name. Value is a list of switches to be used when invoking
4411 the compiler for the language for a source of the project, if there is no
4412 applicable attribute Switches.
4414 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4417 Index is a source file name or a language name. Value is the list of switches
4418 to be used when invoking the compiler for the source or for its language.
4420 @item @b{Local_Configuration_Pragmas}: single
4422 Value is the file name of a configuration pragmas file that is specified to
4423 the Ada compiler when compiling any Ada source in the project.
4425 @item @b{Local_Config_File}: single, indexed, case-insensitive index
4427 Index is a language name. Value is the file name of a configuration file that
4428 is specified to the compiler when compiling any source of the language in the
4433 @item @b{Configuration - Compiling}
4437 @item @b{Driver}: single, indexed, case-insensitive index
4439 Index is a language name. Value is the name of the executable for the compiler
4442 @item @b{Language_Kind}: single, indexed, case-insensitive index
4444 Index is a language name. Indicates the kind of the language, either file based
4445 or unit based. Only authorized case-insensitive values are "unit_based" and
4446 "file_based" (the default).
4448 @item @b{Dependency_Kind}: single, indexed, case-insensitive index
4450 Index is a language name. Indicates how the dependencies are handled for the
4451 language. Only authorized case-insensitive values are "makefile", "ali_file",
4452 "ali_closure" or "none" (the default).
4454 @item @b{Required_Switches}: list, indexed, case-insensitive index
4456 Equivalent to attribute Leading_Required_Switches.
4458 @item @b{Leading_Required_Switches}: list, indexed, case-insensitive index
4460 Index is a language name. Value is the list of the minimum switches to be used
4461 at the beginning of the command line when invoking the compiler for the
4464 @item @b{Trailing_Required_Switches}: list, indexed, case-insensitive index
4466 Index is a language name. Value is the list of the minimum switches to be used
4467 at the end of the command line when invoking the compiler for the language.
4469 @item @b{PIC_Option}: list, indexed, case-insensitive index
4471 Index is a language name. Value is the list of switches to be used when
4472 compiling a source of the language when the project is a shared library
4475 @item @b{Path_Syntax}: single, indexed, case-insensitive index
4477 Index is a language name. Value is the kind of path syntax to be used when
4478 invoking the compiler for the language. Only authorized case-insensitive
4479 values are "canonical" and "host" (the default).
4481 @item @b{Source_File_Switches}: single, indexed, case-insensitive index
4483 Index is a language name. Value is a list of switches to be used just before
4484 the path name of the source to compile when invoking the compiler for a source
4487 @item @b{Object_File_Suffix}: single, indexed, case-insensitive index
4489 Index is a language name. Value is the extension of the object files created
4490 by the compiler of the language. When not specified, the extension is the
4491 default one for the platform.
4493 @item @b{Object_File_Switches}: list, indexed, case-insensitive index
4495 Index is a language name. Value is the list of switches to be used by the
4496 compiler of the language to specify the path name of the object file. When not
4497 specified, the switch used is "-o".
4499 @item @b{Multi_Unit_Switches}: list, indexed, case-insensitive index
4501 Index is a language name. Value is the list of switches to be used to compile
4502 a unit in a multi unit source of the language. The index of the unit in the
4503 source is concatenated with the last switches in the list.
4505 @item @b{Multi_Unit_Object_Separator}: single, indexed, case-insensitive index
4507 Index is a language name. Value is the string to be used in the object file
4508 name before the index of the unit, when compiling a unit in a multi unit source
4513 @item @b{Configuration - Mapping Files}
4517 @item @b{Mapping_File_Switches}: list, indexed, case-insensitive index
4519 Index is a language name. Value is the list of switches to be used to specify
4520 a mapping file when invoking the compiler for a source of the language.
4522 @item @b{Mapping_Spec_Suffix}: single, indexed, case-insensitive index
4524 Index is a language name. Value is the suffix to be used in a mapping file
4525 to indicate that the source is a spec.
4527 @item @b{Mapping_Body_Suffix}: single, indexed, case-insensitive index
4529 Index is a language name. Value is the suffix to be used in a mapping file
4530 to indicate that the source is a body.
4534 @item @b{Configuration - Config Files}
4538 @item @b{Config_File_Switches}: list: single, indexed, case-insensitive index
4540 Index is a language name. Value is the list of switches to specify to the
4541 compiler of the language a configuration file.
4543 @item @b{Config_Body_File_Name}: single, indexed, case-insensitive index
4545 Index is a language name. Value is the template to be used to indicate a
4546 configuration specific to a body of the language in a configuration
4549 @item @b{Config_Body_File_Name_Index}: single, indexed, case-insensitive index
4551 Index is a language name. Value is the template to be used to indicate a
4552 configuration specific to the body a unit in a multi unit source of the
4553 language in a configuration file.
4555 @item @b{Config_Body_File_Name_Pattern}: single, indexed,
4556 case-insensitive index
4558 Index is a language name. Value is the template to be used to indicate a
4559 configuration for all bodies of the languages in a configuration file.
4561 @item @b{Config_Spec_File_Name}: single, indexed, case-insensitive index
4563 Index is a language name. Value is the template to be used to indicate a
4564 configuration specific to a spec of the language in a configuration
4567 @item @b{Config_Spec_File_Name_Index}: single, indexed, case-insensitive index
4569 Index is a language name. Value is the template to be used to indicate a
4570 configuration specific to the spec a unit in a multi unit source of the
4571 language in a configuration file.
4573 @item @b{Config_Spec_File_Name_Pattern}: single, indexed,
4574 case-insensitive index
4576 Index is a language name. Value is the template to be used to indicate a
4577 configuration for all specs of the languages in a configuration file.
4579 @item @b{Config_File_Unique}: single, indexed, case-insensitive index
4581 Index is a language name. Indicates if there should be only one configuration
4582 file specified to the compiler of the language. Only authorized
4583 case-insensitive values are "true" and "false" (the default).
4587 @item @b{Configuration - Dependencies}
4591 @item @b{Dependency_Switches}: list, indexed, case-insensitive index
4593 Index is a language name. Value is the list of switches to be used to specify
4594 to the compiler the dependency file when the dependency kind of the language is
4595 file based, and when Dependency_Driver is not specified for the language.
4597 @item @b{Dependency_Driver}: list, indexed, case-insensitive index
4599 Index is a language name. Value is the name of the executable to be used to
4600 create the dependency file for a source of the language, followed by the
4605 @item @b{Configuration - Search Paths}
4609 @item @b{Include_Switches}: list, indexed, case-insensitive index
4611 Index is a language name. Value is the list of switches to specify to the
4612 compiler of the language to indicate a directory to look for sources.
4614 @item @b{Include_Path}: single, indexed, case-insensitive index
4616 Index is a language name. Value is the name of an environment variable that
4617 contains the path of all the directories that the compiler of the language
4618 may search for sources.
4620 @item @b{Include_Path_File}: single, indexed, case-insensitive index
4622 Index is a language name. Value is the name of an environment variable the
4623 value of which is the path name of a text file that contains the directories
4624 that the compiler of the language may search for sources.
4626 @item @b{Object_Path_Switches}: list, indexed, case-insensitive index
4628 Index is a language name. Value is the list of switches to specify to the
4629 compiler of the language the name of a text file that contains the list of
4630 object directories. When this attribute is not declared, the text file is
4637 @node Package Cross_Reference Attributes
4638 @subsubsection Package Cross_Reference Attributes
4642 @item @b{Default_Switches}: list, indexed, case-insensitive index
4644 Index is a language name. Value is a list of switches to be used when invoking
4645 @code{gnatxref} for a source of the language, if there is no applicable
4648 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4651 Index is a source file name. Value is the list of switches to be used when
4652 invoking @code{gnatxref} for the source.
4657 @node Package Eliminate Attributes
4658 @subsubsection Package Eliminate Attributes
4662 @item @b{Default_Switches}: list, indexed, case-insensitive index
4664 Index is a language name. Value is a list of switches to be used when invoking
4665 @code{gnatelim} for a source of the language, if there is no applicable
4668 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4671 Index is a source file name. Value is the list of switches to be used when
4672 invoking @code{gnatelim} for the source.
4677 @node Package Finder Attributes
4678 @subsubsection Package Finder Attributes
4682 @item @b{Default_Switches}: list, indexed, case-insensitive index
4684 Index is a language name. Value is a list of switches to be used when invoking
4685 @code{gnatfind} for a source of the language, if there is no applicable
4688 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4691 Index is a source file name. Value is the list of switches to be used when
4692 invoking @code{gnatfind} for the source.
4696 @node Package ^gnatls^gnatls^ Attributes
4697 @subsubsection Package ^gnatls^gnatls^ Attributes
4701 @item @b{^Switches^Switches^}: list
4703 Value is a list of switches to be used when invoking @code{gnatls}.
4708 @node Package ^gnatstub^gnatstub^ Attributes
4709 @subsubsection Package ^gnatstub^gnatstub^ Attributes
4713 @item @b{Default_Switches}: list, indexed, case-insensitive index
4715 Index is a language name. Value is a list of switches to be used when invoking
4716 @code{gnatstub} for a source of the language, if there is no applicable
4717 attribute ^Switches^Switches^.
4719 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4722 Index is a source file name. Value is the list of switches to be used when
4723 invoking @code{gnatstub} for the source.
4728 @node Package IDE Attributes
4729 @subsubsection Package IDE Attributes
4733 @item @b{Default_Switches}: list, indexed
4735 Index is the name of an external tool that the GNAT Programming System (GPS)
4736 is supporting. Value is a list of switches to use when invoking that tool.
4738 @item @b{Remote_Host}: single
4740 Value is a string that designates the remote host in a cross-compilation
4741 environment, to be used for remote compilation and debugging. This attribute
4742 should not be specified when running on the local machine.
4744 @item @b{Program_Host}: single
4746 Value is a string that specifies the name of IP address of the embedded target
4747 in a cross-compilation environment, on which the program should execute.
4749 @item @b{Communication_Protocol}: single
4751 Value is the name of the protocol to use to communicate with the target
4752 in a cross-compilation environment, for example @code{"wtx"} or
4755 @item @b{Compiler_Command}: single, indexed, case-insensitive index
4757 Index is a language Name. Value is a string that denotes the command to be
4758 used to invoke the compiler. The value of @code{Compiler_Command ("Ada")} is
4759 expected to be compatible with @command{gnatmake}, in particular in
4760 the handling of switches.
4762 @item @b{Debugger_Command}: single
4764 Value is a string that specifies the name of the debugger to be used, such as
4765 gdb, powerpc-wrs-vxworks-gdb or gdb-4.
4767 @item @b{^gnatlist^gnatlist^}: single
4769 Value is a string that specifies the name of the @command{^gnatls^gnatls^} utility
4770 to be used to retrieve information about the predefined path; for example,
4771 @code{"^gnatls^gnatls^"}, @code{"powerpc-wrs-vxworks-gnatls"}.
4773 @item @b{VCS_Kind}: single
4775 Value is a string used to specify the Version Control System (VCS) to be used
4776 for this project, for example "Subversion", "ClearCase". If the
4777 value is set to "Auto", the IDE will try to detect the actual VCS used
4778 on the list of supported ones.
4780 @item @b{VCS_File_Check}: single
4782 Value is a string that specifies the command used by the VCS to check
4783 the validity of a file, either when the user explicitly asks for a check,
4784 or as a sanity check before doing the check-in.
4786 @item @b{VCS_Log_Check}: single
4788 Value is a string that specifies the command used by the VCS to check
4789 the validity of a log file.
4791 @item @b{Documentation_Dir}: single
4793 Value is the directory used to generate the documentation of source code.
4797 @node Package Install Attributes
4798 @subsubsection Package Install Attributes
4802 @item @b{Prefix}: single
4804 Value is the install destination directory.
4806 @item @b{Sources_Subdir}: single
4808 Value is the sources directory or subdirectory of Prefix.
4810 @item @b{Exec_Subdir}: single
4812 Value is the executables directory or subdirectory of Prefix.
4814 @item @b{Lib_Subdir}: single
4816 Value is library directory or subdirectory of Prefix.
4818 @item @b{Project_Subdir}: single
4820 Value is the project directory or subdirectory of Prefix.
4822 @item @b{Active}: single
4824 Indicates that the project is to be installed or not. Case-insensitive value
4825 "false" means that the project is not to be installed, all other values mean
4826 that the project is to be installed.
4830 @node Package Linker Attributes
4831 @subsubsection Package Linker Attributes
4839 @item @b{Required_Switches}: list
4841 Value is a list of switches that are required when invoking the linker to link
4844 @item @b{Default_Switches}: list, indexed, case-insensitive index
4846 Index is a language name. Value is a list of switches for the linker when
4847 linking an executable for a main source of the language, when there is no
4848 applicable Switches.
4850 @item @b{Leading_Switches}: list, optional index, indexed,
4851 case-insensitive index, others allowed
4853 Index is a source file name or a language name. Value is the list of switches
4854 to be used at the beginning of the command line when invoking the linker to
4855 build an executable for the source or for its language.
4857 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4860 Index is a source file name or a language name. Value is the list of switches
4861 to be used when invoking the linker to build an executable for the source or
4864 @item @b{Trailing_Switches}: list, optional index, indexed,
4865 case-insensitive index, others allowed
4867 Index is a source file name or a language name. Value is the list of switches
4868 to be used at the end of the command line when invoking the linker to
4869 build an executable for the source or for its language. These switches may
4870 override the Required_Switches.
4872 @item @b{Linker_Options}: list
4874 Value is a list of switches/options that are to be added when linking an
4875 executable from a project importing the current project directly or indirectly.
4876 Linker_Options are not used when linking an executable from the current
4879 @item @b{Map_File_Option}: single
4881 Value is the switch to specify the map file name that the linker needs to
4886 @item @b{Configuration - Linking}
4890 @item @b{Driver}: single
4892 Value is the name of the linker executable.
4896 @item @b{Configuration - Response Files}
4900 @item @b{Max_Command_Line_Length}: single
4902 Value is the maximum number of character in the command line when invoking
4903 the linker to link an executable.
4905 @item @b{Response_File_Format}: single
4907 Indicates the kind of response file to create when the length of the linking
4908 command line is too large. Only authorized case-insensitive values are "none",
4909 "gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list".
4911 @item @b{Response_File_Switches}: list
4913 Value is the list of switches to specify a response file to the linker.
4920 @node Package Metrics Attribute
4921 @subsubsection Package Metrics Attribute
4925 @item @b{Default_Switches}: list, indexed, case-insensitive index
4927 Index is a language name. Value is a list of switches to be used when invoking
4928 @code{gnatmetric} for a source of the language, if there is no applicable
4931 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
4934 Index is a source file name. Value is the list of switches to be used when
4935 invoking @code{gnatmetric} for the source.
4940 @node Package Naming Attributes
4941 @subsubsection Package Naming Attributes
4945 @item @b{Specification_Suffix}: single, indexed, case-insensitive index
4947 Equivalent to attribute Spec_Suffix.
4949 @item @b{Spec_Suffix}: single, indexed, case-insensitive index
4951 Index is a language name. Value is the extension of file names for specs of
4954 @item @b{Implementation_Suffix}: single, indexed, case-insensitive index
4956 Equivalent to attribute Body_Suffix.
4958 @item @b{Body_Suffix}: single, indexed, case-insensitive index
4960 Index is a language name. Value is the extension of file names for bodies of
4963 @item @b{Separate_Suffix}: single
4965 Value is the extension of file names for subunits of Ada.
4967 @item @b{Casing}: single
4969 Indicates the casing of sources of the Ada language. Only authorized
4970 case-insensitive values are "lowercase", "uppercase" and "mixedcase".
4972 @item @b{Dot_Replacement}: single
4974 Value is the string that replace the dot of unit names in the source file names
4975 of the Ada language.
4977 @item @b{Specification}: single, optional index, indexed,
4978 case-insensitive index
4980 Equivalent to attribute Spec.
4982 @item @b{Spec}: single, optional index, indexed, case-insensitive index
4984 Index is a unit name. Value is the file name of the spec of the unit.
4986 @item @b{Implementation}: single, optional index, indexed,
4987 case-insensitive index
4989 Equivalent to attribute Body.
4991 @item @b{Body}: single, optional index, indexed, case-insensitive index
4993 Index is a unit name. Value is the file name of the body of the unit.
4995 @item @b{Specification_Exceptions}: list, indexed, case-insensitive index
4997 Index is a language name. Value is a list of specs for the language that do not
4998 necessarily follow the naming scheme for the language and that may or may not
4999 be found in the source directories of the project.
5001 @item @b{Implementation_Exceptions}: list, indexed, case-insensitive index
5003 Index is a language name. Value is a list of bodies for the language that do not
5004 necessarily follow the naming scheme for the language and that may or may not
5005 be found in the source directories of the project.
5010 @node Package Pretty_Printer Attributes
5011 @subsubsection Package Pretty_Printer Attributes
5015 @item @b{Default_Switches}: list, indexed, case-insensitive index
5017 Index is a language name. Value is a list of switches to be used when invoking
5018 @code{gnatpp} for a source of the language, if there is no applicable
5021 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
5024 Index is a source file name. Value is the list of switches to be used when
5025 invoking @code{gnatpp} for the source.
5030 @node Package Remote Attributes
5031 @subsubsection Package Remote Attributes
5035 @item @b{Included_Patterns}: list
5037 If this attribute is defined it sets the patterns to
5038 synchronized from the master to the slaves. It is exclusive
5039 with Excluded_Patterns, that is it is an error to define
5042 @item @b{Included_Artifact_Patterns}: list
5044 If this attribute is defined it sets the patterns of compilation
5045 artifacts to synchronized from the slaves to the build master.
5046 This attribute replace the default hard-coded patterns.
5048 @item @b{Excluded_Patterns}: list
5050 Set of patterns to ignore when synchronizing sources from the build
5051 master to the slaves. A set of predefined patterns are supported
5052 (e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to
5053 add some more patterns.
5055 @item @b{Root_Dir}: single
5057 Value is the root directory used by the slave machines.
5061 @node Package Stack Attributes
5062 @subsubsection Package Stack Attributes
5066 @item @b{^Switches^Switches^}: list
5068 Value is the list of switches to be used when invoking @code{gnatstack}.
5072 @node Package Synchronize Attributes
5073 @subsubsection Package Synchronize Attributes
5077 @item @b{Default_Switches}: list, indexed, case-insensitive index
5079 Index is a language name. Value is a list of switches to be used when invoking
5080 @code{gnatsync} for a source of the language, if there is no applicable
5083 @item @b{^Switches^Switches^}: list, optional index, indexed, case-insensitive index,
5086 Index is a source file name. Value is the list of switches to be used when
5087 invoking @code{gnatsync} for the source.