1 @set gprconfig GPRconfig
3 @c ------ projects.texi
4 @c Copyright (C) 2002-2012, Free Software Foundation, Inc.
5 @c This file is shared between the GNAT user's guide and gprbuild. It is not
6 @c compilable on its own, you should instead compile the other two manuals.
7 @c For that reason, there is no toplevel @menu
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 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
53 @item Automatically build libraries as part of the build process
54 (@pxref{Library Projects}).
59 Project files are written in a syntax close to that of Ada, using familiar
60 notions such as packages, context clauses, declarations, default values,
61 assignments, and inheritance (@pxref{Project File Reference}).
63 Project files can be built hierarchically from other project files, simplifying
64 complex system integration and project reuse (@pxref{Organizing Projects into
68 @item One project can import other projects containing needed source files.
69 More generally, the Project Manager lets you structure large development
70 efforts into hierarchical subsystems, where build decisions are delegated
71 to the subsystem level, and thus different compilation environments
72 (switch settings) used for different subsystems.
73 @item You can organize GNAT projects in a hierarchy: a child project
74 can extend a parent project, inheriting the parent's source files and
75 optionally overriding any of them with alternative versions
76 (@pxref{Project Extension}).
81 Several tools support project files, generally in addition to specifying
82 the information on the command line itself). They share common switches
83 to control the loading of the project (in particular
84 @option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
85 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).
86 @xref{Switches Related to Project Files}.
88 The Project Manager supports a wide range of development strategies,
89 for systems of all sizes. Here are some typical practices that are
93 @item Using a common set of source files and generating object files in different
94 directories via different switch settings. It can be used for instance, for
95 generating separate sets of object files for debugging and for production.
96 @item Using a mostly-shared set of source files with different versions of
97 some units or subunits. It can be used for instance, for grouping and hiding
101 all OS dependencies in a small number of implementation units.
103 Project files can be used to achieve some of the effects of a source
104 versioning system (for example, defining separate projects for
105 the different sets of sources that comprise different releases) but the
106 Project Manager is independent of any source configuration management tool
107 that might be used by the developers.
109 The various sections below introduce the different concepts related to
110 projects. Each section starts with examples and use cases, and then goes into
111 the details of related project file capabilities.
113 @c ---------------------------------------------
114 @node Building With Projects
115 @section Building With Projects
116 @c ---------------------------------------------
119 In its simplest form, a unique project is used to build a single executable.
120 This section concentrates on such a simple setup. Later sections will extend
121 this basic model to more complex setups.
123 The following concepts are the foundation of project files, and will be further
124 detailed later in this documentation. They are summarized here as a reference.
127 @item @b{Project file}:
128 A text file using an Ada-like syntax, generally using the @file{.gpr}
129 extension. It defines build-related characteristics of an application.
130 The characteristics include the list of sources, the location of those
131 sources, the location for the generated object files, the name of
132 the main program, and the options for the various tools involved in the
135 @item @b{Project attribute}:
136 A specific project characteristic is defined by an attribute clause. Its
137 value is a string or a sequence of strings. All settings in a project
138 are defined through a list of predefined attributes with precise
139 semantics. @xref{Attributes}.
141 @item @b{Package in a project}:
142 Global attributes are defined at the top level of a project.
143 Attributes affecting specific tools are grouped in a
144 package whose name is related to tool's function. The most common
145 packages are @code{Builder}, @code{Compiler}, @code{Binder},
146 and @code{Linker}. @xref{Packages}.
148 @item @b{Project variables}:
149 In addition to attributes, a project can use variables to store intermediate
150 values and avoid duplication in complex expressions. It can be initialized
151 with a value coming from the environment.
152 A frequent use of variables is to define scenarios.
153 @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.
155 @item @b{Source files} and @b{source directories}:
156 A source file is associated with a language through a naming convention. For
157 instance, @code{foo.c} is typically the name of a C source file;
158 @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a
159 file containing an Ada spec. A compilation unit is often composed of a main
160 source file and potentially several auxiliary ones, such as header files in C.
161 The naming conventions can be user defined @xref{Naming Schemes}, and will
162 drive the builder to call the appropriate compiler for the given source file.
163 Source files are searched for in the source directories associated with the
164 project through the @b{Source_Dirs} attribute. By default, all the files (in
165 these source directories) following the naming conventions associated with the
166 declared languages are considered to be part of the project. It is also
167 possible to limit the list of source files using the @b{Source_Files} or
168 @b{Source_List_File} attributes. Note that those last two attributes only
169 accept basenames with no directory information.
171 @item @b{Object files} and @b{object directory}:
172 An object file is an intermediate file produced by the compiler from a
173 compilation unit. It is used by post-compilation tools to produce
174 final executables or libraries. Object files produced in the context of
175 a given project are stored in a single directory that can be specified by the
176 @b{Object_Dir} attribute. In order to store objects in
177 two or more object directories, the system must be split into
178 distinct subsystems with their own project file.
182 The following subsections introduce gradually all the attributes of interest
183 for simple build needs. Here is the simple setup that will be used in the
186 The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in
187 the @file{common/} directory. The file @file{proc.adb} contains an Ada main
188 subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile
189 these source files with the switch @option{-O2}, and put the resulting files in
190 the directory @file{obj/}.
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 * Object and Exec Directory::
224 * Tools Options in Project Files::
225 * Compiling with Project Files::
226 * Executable File Names::
227 * Avoid Duplication With Variables::
231 @c ---------------------------------------------
232 @node Source Files and Directories
233 @subsection Source Files and Directories
234 @c ---------------------------------------------
237 When you create a new project, the first thing to describe is how to find the
238 corresponding source files. This is the only settings that are needed by all
239 the tools that will use this project (builder, compiler, binder and linker for
240 the compilation, IDEs to edit the source files,@dots{}).
242 @cindex Source directories
243 First step is to declare the source directories, which are the directories
244 to be searched to find source files. In the case of the example,
245 the @file{common} directory is the only source directory.
247 @cindex @code{Source_Dirs}
248 There are several ways of defining source directories:
251 @item When the attribute @b{Source_Dirs} is not used, a project contains a
252 single source directory which is the one where the project file itself
253 resides. In our example, if @file{build.gpr} is placed in the @file{common}
254 directory, the project has the needed implicit source directory.
256 @item The attribute @b{Source_Dirs} can be set to a list of path names, one
257 for each of the source directories. Such paths can either be absolute
258 names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the
259 directory in which the project file resides (for instance "." if
260 @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
261 Each of the source directories must exist and be readable.
264 The syntax for directories is platform specific. For portability, however,
265 the project manager will always properly translate UNIX-like path names to
266 the native format of specific platform. For instance, when the same project
267 file is to be used both on Unix and Windows, "/" should be used as the
268 directory separator rather than "\".
270 @item The attribute @b{Source_Dirs} can automatically include subdirectories
271 using a special syntax inspired by some UNIX shells. If any of the path in
272 the list ends with @emph{"**"}, then that path and all its subdirectories
273 (recursively) are included in the list of source directories. For instance,
274 @file{**} and @file{./**} represent the complete directory tree rooted at ".".
275 @cindex Source directories, recursive
277 @cindex @code{Excluded_Source_Dirs}
278 When using that construct, it can sometimes be convenient to also use the
279 attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry
280 specifies a directory whose immediate content, not including subdirs, is to
281 be excluded. It is also possible to exclude a complete directory subtree
282 using the "**" notation.
284 @cindex @code{Ignore_Source_Sub_Dirs}
285 It is often desirable to remove, from the source directories, directory
286 subtrees rooted at some subdirectories. An example is the subdirectories
287 created by a Version Control System such as Subversion that creates directory
288 subtrees .svn/**. To do that, attribute @b{Ignore_Source_Sub_Dirs} can be
289 used. It specifies the list of simple file names for the root of these
290 undesirable directory subtrees.
295 When applied to the simple example, and because we generally prefer to have
296 the project file at the toplevel directory rather than mixed with the sources,
297 we will create the following file
301 @b{project} Build @b{is}
302 @b{for} Source_Dirs @b{use} ("common"); -- <<<<
307 Once source directories have been specified, one may need to indicate
308 source files of interest. By default, all source files present in the source
309 directories are considered by the project manager. When this is not desired,
310 it is possible to specify the list of sources to consider explicitly.
311 In such a case, only source file base names are indicated and not
312 their absolute or relative path names. The project manager is in charge of
313 locating the specified source files in the specified source directories.
316 @item By default, the project manager search for all source files of all
317 specified languages in all the source directories.
319 Since the project manager was initially developed for Ada environments, the
320 default language is usually Ada and the above project file is complete: it
321 defines without ambiguity the sources composing the project: that is to say,
322 all the sources in subdirectory "common" for the default language (Ada) using
323 the default naming convention.
325 @cindex @code{Languages}
326 However, when compiling a multi-language application, or a pure C
327 application, the project manager must be told which languages are of
328 interest, which is done by setting the @b{Languages} attribute to a list of
329 strings, each of which is the name of a language. Tools like
330 @command{gnatmake} only know about Ada, while other tools like
331 @command{gprbuild} know about many more languages such as C, C++, Fortran,
332 assembly and others can be added dynamically.
334 @cindex Naming scheme
335 Even when using only Ada, the default naming might not be suitable. Indeed,
336 how does the project manager recognizes an "Ada file" from any other
337 file? Project files can describe the naming scheme used for source files,
338 and override the default (@pxref{Naming Schemes}). The default is the
339 standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
340 specs), which is what is used in our example, explaining why no naming scheme
341 is explicitly specified.
342 @xref{Naming Schemes}.
344 @item @code{Source Files}
345 @cindex @code{Source_Files}
346 In some cases, source directories might contain files that should not be
347 included in a project. One can specify the explicit list of file names to
348 be considered through the @b{Source_Files} attribute.
349 When this attribute is defined, instead of looking at every file in the
350 source directories, the project manager takes only those names into
351 consideration reports errors if they cannot be found in the source
352 directories or does not correspond to the naming scheme.
354 @item For various reasons, it is sometimes useful to have a project with no
355 sources (most of the time because the attributes defined in the project
356 file will be reused in other projects, as explained in @pxref{Organizing
357 Projects into Subsystems}. To do this, the attribute
358 @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
359 @emph{Source_Dirs} can be set to the empty list, with the same
362 @item @code{Source_List_File}
363 @cindex @code{Source_List_File}
364 If there is a great number of files, it might be more convenient to use
365 the attribute @b{Source_List_File}, which specifies the full path of a file.
366 This file must contain a list of source file names (one per line, no
367 directory information) that are searched as if they had been defined
368 through @emph{Source_Files}. Such a file can easily be created through
371 A warning is issued if both attributes @code{Source_Files} and
372 @code{Source_List_File} are given explicit values. In this case, the
373 attribute @code{Source_Files} prevails.
375 @item @code{Excluded_Source_Files}
376 @cindex @code{Excluded_Source_Files}
377 @cindex @code{Locally_Removed_Files}
378 @cindex @code{Excluded_Source_List_File}
379 Specifying an explicit list of files is not always convenient.It might be
380 more convenient to use the default search rules with specific exceptions.
381 This can be done thanks to the attribute @b{Excluded_Source_Files}
382 (or its synonym @b{Locally_Removed_Files}).
383 Its value is the list of file names that should not be taken into account.
384 This attribute is often used when extending a project, @xref{Project
385 Extension}. A similar attribute @b{Excluded_Source_List_File} plays the same
386 role but takes the name of file containing file names similarly to
387 @code{Source_List_File}.
392 In most simple cases, such as the above example, the default source file search
393 behavior provides the expected result, and we do not need to add anything after
394 setting @code{Source_Dirs}. The project manager automatically finds
395 @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the
398 Note that it is considered an error for a project file to have no sources
399 attached to it unless explicitly declared as mentioned above.
401 If the order of the source directories is known statically, that is if
402 @code{"**"} is not used in the string list @code{Source_Dirs}, then there may
403 be several files with the same source file name sitting in different
404 directories of the project. In this case, only the file in the first directory
405 is considered as a source of the project and the others are hidden. If
406 @code{"**"} is not used in the string list @code{Source_Dirs}, it is an error
407 to have several files with the same source file name in the same directory
408 @code{"**"} subtree, since there would be an ambiguity as to which one should
409 be used. However, two files with the same source file name may in two single
410 directories or directory subtrees. In this case, the one in the first directory
411 or directory subtree is a source of the project.
413 @c ---------------------------------------------
414 @node Object and Exec Directory
415 @subsection Object and Exec Directory
416 @c ---------------------------------------------
419 The next step when writing a project is to indicate where the compiler should
420 put the object files. In fact, the compiler and other tools might create
421 several different kind of files (for GNAT, there is the object file and the ALI
422 file for instance). One of the important concepts in projects is that most
423 tools may consider source directories as read-only and do not attempt to create
424 new or temporary files there. Instead, all files are created in the object
425 directory. It is of course not true for project-aware IDEs, whose purpose it is
426 to create the source files.
428 @cindex @code{Object_Dir}
429 The object directory is specified through the @b{Object_Dir} attribute.
430 Its value is the path to the object directory, either absolute or
431 relative to the directory containing the project file. This
432 directory must already exist and be readable and writable, although
433 some tools have a switch to create the directory if needed (See
434 the switch @code{-p} for @command{gnatmake} and @command{gprbuild}).
436 If the attribute @code{Object_Dir} is not specified, it defaults to
437 the project directory, that is the directory containing the project file.
439 For our example, we can specify the object dir in this way:
442 @b{project} Build @b{is}
443 @b{for} Source_Dirs @b{use} ("common");
444 @b{for} Object_Dir @b{use} "obj"; -- <<<<
449 As mentioned earlier, there is a single object directory per project. As a
450 result, if you have an existing system where the object files are spread in
451 several directories, you can either move all of them into the same directory if
452 you want to build it with a single project file, or study the section on
453 subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
454 separate object directory can be associated with one of the subsystem
455 constituting the application.
457 When the @command{linker} is called, it usually creates an executable. By
458 default, this executable is placed in the object directory of the project. It
459 might be convenient to store it in its own directory.
461 @cindex @code{Exec_Dir}
462 This can be done through the @code{Exec_Dir} attribute, which, like
463 @emph{Object_Dir} contains a single absolute or relative path and must point to
464 an existing and writable directory, unless you ask the tool to create it on
465 your behalf. When not specified, It defaults to the object directory and
466 therefore to the project file's directory if neither @emph{Object_Dir} nor
467 @emph{Exec_Dir} was specified.
469 In the case of the example, let's place the executable in the root
470 of the hierarchy, ie the same directory as @file{build.gpr}. Hence
471 the project file is now
474 @b{project} Build @b{is}
475 @b{for} Source_Dirs @b{use} ("common");
476 @b{for} Object_Dir @b{use} "obj";
477 @b{for} Exec_Dir @b{use} "."; -- <<<<
481 @c ---------------------------------------------
482 @node Main Subprograms
483 @subsection Main Subprograms
484 @c ---------------------------------------------
487 In the previous section, executables were mentioned. The project manager needs
488 to be taught what they are. In a project file, an executable is indicated by
489 pointing to source file of the main subprogram. In C this is the file that
490 contains the @code{main} function, and in Ada the file that contains the main
493 There can be any number of such main files within a given project, and thus
494 several executables can be built in the context of a single project file. Of
495 course, one given executable might not (and in fact will not) need all the
496 source files referenced by the project. As opposed to other build environments
497 such as @command{makefile}, one does not need to specify the list of
498 dependencies of each executable, the project-aware builders knows enough of the
499 semantics of the languages to build ands link only the necessary elements.
502 The list of main files is specified via the @b{Main} attribute. It contains
503 a list of file names (no directories). If a project defines this
504 attribute, it is not necessary to identify main files on the
505 command line when invoking a builder, and editors like
506 @command{GPS} will be able to create extra menus to spawn or debug the
507 corresponding executables.
510 @b{project} Build @b{is}
511 @b{for} Source_Dirs @b{use} ("common");
512 @b{for} Object_Dir @b{use} "obj";
513 @b{for} Exec_Dir @b{use} ".";
514 @b{for} Main @b{use} ("proc.adb"); -- <<<<
519 If this attribute is defined in the project, then spawning the builder
520 with a command such as
523 gnatmake ^-Pbuild^/PROJECT_FILE=build^
527 automatically builds all the executables corresponding to the files
528 listed in the @emph{Main} attribute. It is possible to specify one
529 or more executables on the command line to build a subset of them.
531 @c ---------------------------------------------
532 @node Tools Options in Project Files
533 @subsection Tools Options in Project Files
534 @c ---------------------------------------------
537 We now have a project file that fully describes our environment, and can be
538 used to build the application with a simple @command{gnatmake} command as seen
539 in the previous section. In fact, the empty project we showed immediately at
540 the beginning (with no attribute at all) could already fulfill that need if it
541 was put in the @file{common} directory.
543 Of course, we always want more control. This section will show you how to
544 specify the compilation switches that the various tools involved in the
545 building of the executable should use.
547 @cindex command line length
548 Since source names and locations are described into the project file, it is not
549 necessary to use switches on the command line for this purpose (switches such
550 as -I for gcc). This removes a major source of command line length overflow.
551 Clearly, the builders will have to communicate this information one way or
552 another to the underlying compilers and tools they call but they usually use
553 response files for this and thus should not be subject to command line
556 Several tools are participating to the creation of an executable: the compiler
557 produces object files from the source files; the binder (in the Ada case)
558 creates an source file that takes care, among other things, of elaboration
559 issues and global variables initialization; and the linker gathers everything
560 into a single executable that users can execute. All these tools are known by
561 the project manager and will be called with user defined switches from the
562 project files. However, we need to introduce a new project file concept to
563 express which switches to be used for any of the tools involved in the build.
565 @cindex project file packages
566 A project file is subdivided into zero or more @b{packages}, each of which
567 contains the attributes specific to one tool (or one set of tools). Project
568 files use an Ada-like syntax for packages. Package names permitted in project
569 files are restricted to a predefined set (@pxref{Packages}), and the contents
570 of packages are limited to a small set of constructs and attributes
571 (@pxref{Attributes}).
573 Our example project file can be extended with the following empty packages. At
574 this stage, they could all be omitted since they are empty, but they show which
575 packages would be involved in the build process.
578 @b{project} Build @b{is}
579 @b{for} Source_Dirs @b{use} ("common");
580 @b{for} Object_Dir @b{use} "obj";
581 @b{for} Exec_Dir @b{use} ".";
582 @b{for} Main @b{use} ("proc.adb");
584 @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
587 @b{package} Compiler @b{is} --<<< for the compiler
590 @b{package} Binder @b{is} --<<< for the binder
593 @b{package} Linker @b{is} --<<< for the linker
599 Let's first examine the compiler switches. As stated in the initial description
600 of the example, we want to compile all files with @option{-O2}. This is a
601 compiler switch, although it is usual, on the command line, to pass it to the
602 builder which then passes it to the compiler. It is recommended to use directly
603 the right package, which will make the setup easier to understand for other
606 Several attributes can be used to specify the switches:
609 @item @b{Default_Switches}:
610 @cindex @code{Default_Switches}
611 This is the first mention in this manual of an @b{indexed attribute}. When
612 this attribute is defined, one must supply an @emph{index} in the form of a
614 In the case of @emph{Default_Switches}, the index is the name of the
615 language to which the switches apply (since a different compiler will
616 likely be used for each language, and each compiler has its own set of
617 switches). The value of the attribute is a list of switches.
619 In this example, we want to compile all Ada source files with the
620 @option{-O2} switch, and the resulting project file is as follows
621 (only the @code{Compiler} package is shown):
624 @b{package} Compiler @b{is}
625 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
630 @cindex @code{Switches}
631 in some cases, we might want to use specific switches
632 for one or more files. For instance, compiling @file{proc.adb} might not be
633 possible at high level of optimization because of a compiler issue.
634 In such a case, the @emph{Switches}
635 attribute (indexed on the file name) can be used and will override the
636 switches defined by @emph{Default_Switches}. Our project file would
640 @b{package} Compiler @b{is}
641 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
642 @b{for} Switches ("proc.adb") @b{use} ("-O0");
647 @code{Switches} may take a pattern as an index, such as in:
650 @b{package} Compiler @b{is}
651 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
652 @b{for} Switches ("pkg*") @b{use} ("-O0");
657 Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0,
661 @code{Switches} can also be given a language name as index instead of a file
662 name in which case it has the same semantics as @emph{Default_Switches}.
663 However, indexes with wild cards are never valid for language name.
665 @item @b{Local_Configuration_Pragmas}:
666 @cindex @code{Local_Configuration_Pragmas}
667 this attribute may specify the path
668 of a file containing configuration pragmas for use by the Ada compiler,
669 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
670 used for all the sources of the project.
674 The switches for the other tools are defined in a similar manner through the
675 @b{Default_Switches} and @b{Switches} attributes, respectively in the
676 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
677 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
678 package (for linking executables).
680 @c ---------------------------------------------
681 @node Compiling with Project Files
682 @subsection Compiling with Project Files
683 @c ---------------------------------------------
686 Now that our project files are written, let's build our executable.
687 Here is the command we would use from the command line:
690 gnatmake ^-Pbuild^/PROJECT_FILE=build^
694 This will automatically build the executables specified through the
695 @emph{Main} attribute: for each, it will compile or recompile the
696 sources for which the object file does not exist or is not up-to-date; it
697 will then run the binder; and finally run the linker to create the
700 @command{gnatmake} only knows how to handle Ada files. By using
701 @command{gprbuild} as a builder, you could automatically manage C files the
702 same way: create the file @file{utils.c} in the @file{common} directory,
703 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
706 gprbuild ^-Pbuild^/PROJECT_FILE=build^
710 Gprbuild knows how to recompile the C files and will
711 recompile them only if one of their dependencies has changed. No direct
712 indication on how to build the various elements is given in the
713 project file, which describes the project properties rather than a
714 set of actions to be executed. Here is the invocation of
715 @command{gprbuild} when building a multi-language program:
728 Notice the three steps described earlier:
731 @item The first three gcc commands correspond to the compilation phase.
732 @item The gprbind command corresponds to the post-compilation phase.
733 @item The last gcc command corresponds to the final link.
738 @cindex @option{-v} option (for GPRbuild)
739 The default output of GPRbuild's execution is kept reasonably simple and easy
740 to understand. In particular, some of the less frequently used commands are not
741 shown, and some parameters are abbreviated. So it is not possible to rerun the
742 effect of the @command{gprbuild} command by cut-and-pasting its output.
743 GPRbuild's option @code{-v} provides a much more verbose output which includes,
744 among other information, more complete compilation, post-compilation and link
747 @c ---------------------------------------------
748 @node Executable File Names
749 @subsection Executable File Names
750 @c ---------------------------------------------
753 @cindex @code{Executable}
754 By default, the executable name corresponding to a main file is
755 computed from the main source file name. Through the attribute
756 @b{Builder.Executable}, it is possible to change this default.
758 For instance, instead of building @command{proc} (or @command{proc.exe}
759 on Windows), we could configure our project file to build "proc1"
760 (resp proc1.exe) with the following addition:
762 @smallexample @c projectfile
764 ... -- same as before
766 for Executable ("proc.adb") use "proc1";
772 @cindex @code{Executable_Suffix}
773 Attribute @b{Executable_Suffix}, when specified, may change the suffix
774 of the executable files, when no attribute @code{Executable} applies:
775 its value replace the platform-specific executable suffix.
776 The default executable suffix is empty on UNIX and ".exe" on Windows.
778 It is also possible to change the name of the produced executable by using the
779 command line switch @option{-o}. When several mains are defined in the project,
780 it is not possible to use the @option{-o} switch and the only way to change the
781 names of the executable is provided by Attributes @code{Executable} and
782 @code{Executable_Suffix}.
784 @c ---------------------------------------------
785 @node Avoid Duplication With Variables
786 @subsection Avoid Duplication With Variables
787 @c ---------------------------------------------
790 To illustrate some other project capabilities, here is a slightly more complex
791 project using similar sources and a main program in C:
793 @smallexample @c projectfile
795 for Languages use ("Ada", "C");
796 for Source_Dirs use ("common");
797 for Object_Dir use "obj";
798 for Main use ("main.c");
800 C_Switches := ("-pedantic");
801 for Default_Switches ("C") use C_Switches;
802 for Default_Switches ("Ada") use ("-gnaty");
803 for Switches ("main.c") use C_Switches & ("-g");
809 This project has many similarities with the previous one.
810 As expected, its @code{Main} attribute now refers to a C source.
811 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
812 executable will be put in the directory @file{obj}.
814 The most noticeable difference is the use of a variable in the
815 @emph{Compiler} package to store settings used in several attributes.
816 This avoids text duplication, and eases maintenance (a single place to
817 modify if we want to add new switches for C files). We will revisit
818 the use of variables in the context of scenarios (@pxref{Scenarios in
821 In this example, we see how the file @file{main.c} can be compiled with
822 the switches used for all the other C files, plus @option{-g}.
823 In this specific situation the use of a variable could have been
824 replaced by a reference to the @code{Default_Switches} attribute:
826 @smallexample @c projectfile
827 for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
831 Note the tick (@emph{'}) used to refer to attributes defined in a package.
833 Here is the output of the GPRbuild command using this project:
837 gcc -c -pedantic -g main.c
838 gcc -c -gnaty proc.adb
839 gcc -c -gnaty pack.adb
840 gcc -c -pedantic utils.c
847 The default switches for Ada sources,
848 the default switches for C sources (in the compilation of @file{lib.c}),
849 and the specific switches for @file{main.c} have all been taken into
852 @c ---------------------------------------------
854 @subsection Naming Schemes
855 @c ---------------------------------------------
858 Sometimes an Ada software system is ported from one compilation environment to
859 another (say GNAT), and the file are not named using the default GNAT
860 conventions. Instead of changing all the file names, which for a variety of
861 reasons might not be possible, you can define the relevant file naming scheme
862 in the @b{Naming} package of your project file.
864 The naming scheme has two distinct goals for the project manager: it
865 allows finding of source files when searching in the source
866 directories, and given a source file name it makes it possible to guess
867 the associated language, and thus the compiler to use.
869 Note that the use by the Ada compiler of pragmas Source_File_Name is not
870 supported when using project files. You must use the features described in this
871 paragraph. You can however specify other configuration pragmas
872 (@pxref{Specifying Configuration Pragmas}).
874 The following attributes can be defined in package @code{Naming}:
878 @cindex @code{Casing}
879 Its value must be one of @code{"lowercase"} (the default if
880 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
881 casing of file names with regards to the Ada unit name. Given an Ada unit
882 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
883 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
884 On Windows, file names are case insensitive, so this attribute is
887 @item @b{Dot_Replacement}:
888 @cindex @code{Dot_Replacement}
889 This attribute specifies the string that should replace the "." in unit
890 names. Its default value is @code{"-"} so that a unit
891 @code{Parent.Child} is expected to be found in the file
892 @file{parent-child.adb}. The replacement string must satisfy the following
893 requirements to avoid ambiguities in the naming scheme:
896 @item It must not be empty
897 @item It cannot start or end with an alphanumeric character
898 @item It cannot be a single underscore
899 @item It cannot start with an underscore followed by an alphanumeric
900 @item It cannot contain a dot @code{'.'} except if the entire string
905 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
906 @cindex @code{Spec_Suffix}
907 @cindex @code{Specification_Suffix}
908 For Ada, these attributes give the suffix used in file names that contain
909 specifications. For other languages, they give the extension for files
910 that contain declaration (header files in C for instance). The attribute
911 is indexed on the language.
912 The two attributes are equivalent, but the latter is obsolescent.
913 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
914 @code{"^.ads^.ADS^"}.
915 The value must satisfy the following requirements:
918 @item It must not be empty
919 @item It cannot start with an alphanumeric character
920 @item It cannot start with an underscore followed by an alphanumeric character
921 @item It must include at least one dot
925 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
926 @cindex @code{Body_Suffix}
927 @cindex @code{Implementation_Suffix}
928 These attributes give the extension used for file names that contain
929 code (bodies in Ada). They are indexed on the language. The second
930 version is obsolescent and fully replaced by the first attribute.
932 These attributes must satisfy the same requirements as @code{Spec_Suffix}.
933 In addition, they must be different from any of the values in
935 If @code{Body_Suffix ("Ada")} is not specified, then the default is
936 @code{"^.adb^.ADB^"}.
938 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
939 same string, then a file name that ends with the longest of these two
940 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
941 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
943 If the suffix does not start with a '.', a file with a name exactly equal
944 to the suffix will also be part of the project (for instance if you define
945 the suffix as @code{Makefile}, a file called @file{Makefile} will be part
946 of the project. This capability is usually not interesting when building.
947 However, it might become useful when a project is also used to
948 find the list of source files in an editor, like the GNAT Programming System
951 @item @b{Separate_Suffix}:
952 @cindex @code{Separate_Suffix}
953 This attribute is specific to Ada. It denotes the suffix used in file names
954 that contain separate bodies. If it is not specified, then it defaults to
955 same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the
956 @code{Body_Suffix} attribute. The only accepted index is "Ada".
958 @item @b{Spec} or @b{Specification}:
960 @cindex @code{Specification}
961 This attribute @code{Spec} can be used to define the source file name for a
962 given Ada compilation unit's spec. The index is the literal name of the Ada
963 unit (case insensitive). The value is the literal base name of the file that
964 contains this unit's spec (case sensitive or insensitive depending on the
965 operating system). This attribute allows the definition of exceptions to the
966 general naming scheme, in case some files do not follow the usual
969 When a source file contains several units, the relative position of the unit
970 can be indicated. The first unit in the file is at position 1
972 @smallexample @c projectfile
973 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
974 for Spec ("top") use "foo.a" at 1;
975 for Spec ("foo") use "foo.a" at 2;
978 @item @b{Body} or @b{Implementation}:
980 @cindex @code{Implementation}
981 These attribute play the same role as @emph{Spec} for Ada bodies.
983 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
984 @cindex @code{Specification_Exceptions}
985 @cindex @code{Implementation_Exceptions}
986 These attributes define exceptions to the naming scheme for languages
987 other than Ada. They are indexed on the language name, and contain
988 a list of file names respectively for headers and source code.
993 For example, the following package models the Apex file naming rules:
995 @smallexample @c projectfile
998 for Casing use "lowercase";
999 for Dot_Replacement use ".";
1000 for Spec_Suffix ("Ada") use ".1.ada";
1001 for Body_Suffix ("Ada") use ".2.ada";
1008 For example, the following package models the DEC Ada file naming rules:
1010 @smallexample @c projectfile
1013 for Casing use "lowercase";
1014 for Dot_Replacement use "__";
1015 for Spec_Suffix ("Ada") use "_.ada";
1016 for Body_Suffix ("Ada") use ".ada";
1022 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1023 names in lower case)
1026 @c ---------------------------------------------
1027 @node Organizing Projects into Subsystems
1028 @section Organizing Projects into Subsystems
1029 @c ---------------------------------------------
1032 A @b{subsystem} is a coherent part of the complete system to be built. It is
1033 represented by a set of sources and one single object directory. A system can
1034 be composed of a single subsystem when it is simple as we have seen in the
1035 first section. Complex systems are usually composed of several interdependent
1036 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1037 other one is required to build it, and in particular if visibility on some of
1038 the sources of this other subsystem is required. Each subsystem is usually
1039 represented by its own project file.
1041 In this section, the previous example is being extended. Let's assume some
1042 sources of our @code{Build} project depend on other sources.
1043 For instance, when building a graphical interface, it is usual to depend upon
1044 a graphical library toolkit such as GtkAda. Furthermore, we also need
1045 sources from a logging module we had previously written.
1048 * Project Dependencies::
1049 * Cyclic Project Dependencies::
1050 * Sharing Between Projects::
1051 * Global Attributes::
1054 @c ---------------------------------------------
1055 @node Project Dependencies
1056 @subsection Project Dependencies
1057 @c ---------------------------------------------
1060 GtkAda comes with its own project file (appropriately called
1061 @file{gtkada.gpr}), and we will assume we have already built a project
1062 called @file{logging.gpr} for the logging module. With the information provided
1063 so far in @file{build.gpr}, building the application would fail with an error
1064 indicating that the gtkada and logging units that are relied upon by the sources
1065 of this project cannot be found.
1067 This is easily solved by adding the following @b{with} clauses at the beginning
1070 @smallexample @c projectfile
1072 with "a/b/logging.gpr";
1079 @cindex @code{Externally_Built}
1080 When such a project is compiled, @command{gnatmake} will automatically
1081 check the other projects and recompile their sources when needed. It will also
1082 recompile the sources from @code{Build} when needed, and finally create the
1083 executable. In some cases, the implementation units needed to recompile a
1084 project are not available, or come from some third-party and you do not want to
1085 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1086 "true" can be set, indicating to the builder that this project can be assumed
1087 to be up-to-date, and should not be considered for recompilation. In Ada, if
1088 the sources of this externally built project were compiled with another version
1089 of the compiler or with incompatible options, the binder will issue an error.
1091 The project's @code{with} clause has several effects. It provides source
1092 visibility between projects during the compilation process. It also guarantees
1093 that the necessary object files from @code{Logging} and @code{GtkAda} are
1094 available when linking @code{Build}.
1096 As can be seen in this example, the syntax for importing projects is similar
1097 to the syntax for importing compilation units in Ada. However, project files
1098 use literal strings instead of names, and the @code{with} clause identifies
1099 project files rather than packages.
1101 Each literal string after @code{with} is the path
1102 (absolute or relative) to a project file. The @code{.gpr} extension is
1103 optional, although we recommend adding it. If no extension is specified,
1104 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1105 the file is searched for exactly as written in the @code{with} clause,
1106 that is with no extension.
1108 As mentioned above, the path after a @code{with} has to be a literal
1109 string, and you cannot use concatenation, or lookup the value of external
1110 variables to change the directories from which a project is loaded.
1111 A solution if you need something like this is to use aggregate projects
1112 (@pxref{Aggregate Projects}).
1114 @cindex project path
1115 When a relative path or a base name is used, the
1116 project files are searched relative to each of the directories in the
1117 @b{project path}. This path includes all the directories found with the
1118 following algorithm, in that order, as soon as a matching file is found,
1122 @item First, the file is searched relative to the directory that contains the
1123 current project file.
1126 @cindex @code{ADA_PROJECT_PATH}
1127 @cindex @code{GPR_PROJECT_PATH}
1128 Then it is searched relative to all the directories specified in the
1129 ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and
1130 @b{ADA_PROJECT_PATH} (in that order) if they exist. The former is
1131 recommended, the latter is kept for backward compatibility.
1133 @item Finally, it is searched relative to the default project directories.
1134 Such directories depends on the tool used. The different locations searched
1135 in the specified order are:
1138 @item @file{<prefix>/<target>/lib/gnat}
1139 (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
1140 @option{--target} is specified)
1141 @item @file{<prefix>/share/gpr/}
1142 (for @command{gnatmake} and @command{gprbuild})
1143 @item @file{<prefix>/lib/gnat/}
1144 (for @command{gnatmake} and @command{gprbuild})
1147 In our example, @file{gtkada.gpr} is found in the predefined directory if
1148 it was installed at the same root as GNAT.
1152 Some tools also support extending the project path from the command line,
1153 generally through the @option{-aP}. You can see the value of the project
1154 path by using the @command{gnatls -v} command.
1156 Any symbolic link will be fully resolved in the directory of the
1157 importing project file before the imported project file is examined.
1159 Any source file in the imported project can be used by the sources of the
1160 importing project, transitively.
1161 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1162 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1163 import @code{C} explicitly. However, this is not recommended, because if
1164 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1165 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1166 that will report such indirect dependencies.
1168 One very important aspect of a project hierarchy is that
1169 @b{a given source can only belong to one project} (otherwise the project manager
1170 would not know which settings apply to it and when to recompile it). It means
1171 that different project files do not usually share source directories or
1172 when they do, they need to specify precisely which project owns which sources
1173 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1174 can each own a source with the same base file name as long as they live in
1175 different directories. The latter is not true for Ada Sources because of the
1176 correlation between source files and Ada units.
1178 @c ---------------------------------------------
1179 @node Cyclic Project Dependencies
1180 @subsection Cyclic Project Dependencies
1181 @c ---------------------------------------------
1184 Cyclic dependencies are mostly forbidden:
1185 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1186 is not allowed to import @code{A}. However, there are cases when cyclic
1187 dependencies would be beneficial. For these cases, another form of import
1188 between projects exists: the @b{limited with}. A project @code{A} that
1189 imports a project @code{B} with a straight @code{with} may also be imported,
1190 directly or indirectly, by @code{B} through a @code{limited with}.
1192 The difference between straight @code{with} and @code{limited with} is that
1193 the name of a project imported with a @code{limited with} cannot be used in the
1194 project importing it. In particular, its packages cannot be renamed and
1195 its variables cannot be referred to.
1197 @smallexample @c 0projectfile
1201 For Exec_Dir use B'Exec_Dir; -- ok
1204 limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
1206 For Exec_Dir use A'Exec_Dir; -- not ok
1213 limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
1215 For Exec_Dir use A'Exec_Dir; -- not ok
1219 @c ---------------------------------------------
1220 @node Sharing Between Projects
1221 @subsection Sharing Between Projects
1222 @c ---------------------------------------------
1225 When building an application, it is common to have similar needs in several of
1226 the projects corresponding to the subsystems under construction. For instance,
1227 they will all have the same compilation switches.
1229 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1230 switches for all sources of a subsystem is simple: it is just a matter of
1231 adding a @code{Compiler.Default_Switches} attribute to each project files with
1232 the same value. Of course, that means duplication of data, and both places need
1233 to be changed in order to recompile the whole application with different
1234 switches. It can become a real problem if there are many subsystems and thus
1235 many project files to edit.
1237 There are two main approaches to avoiding this duplication:
1240 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1241 to reference the attribute in Logging, either through a package renaming,
1242 or by referencing the attribute. The following example shows both cases:
1244 @smallexample @c projectfile
1247 for Switches ("Ada") use ("-O2");
1250 for Switches ("Ada") use ("-E");
1256 package Compiler renames Logging.Compiler;
1258 for Switches ("Ada") use Logging.Binder'Switches ("Ada");
1264 The solution used for @code{Compiler} gets the same value for all
1265 attributes of the package, but you cannot modify anything from the
1266 package (adding extra switches or some exceptions). The second
1267 version is more flexible, but more verbose.
1269 If you need to refer to the value of a variable in an imported
1270 project, rather than an attribute, the syntax is similar but uses
1271 a "." rather than an apostrophe. For instance:
1273 @smallexample @c projectfile
1276 Var1 := Imported.Var;
1280 @item The second approach is to define the switches in a third project.
1281 That project is setup without any sources (so that, as opposed to
1282 the first example, none of the project plays a special role), and
1283 will only be used to define the attributes. Such a project is
1284 typically called @file{shared.gpr}.
1286 @smallexample @c projectfile
1287 abstract project Shared is
1288 for Source_Files use (); -- no project
1290 for Switches ("Ada") use ("-O2");
1296 package Compiler renames Shared.Compiler;
1301 package Compiler renames Shared.Compiler;
1306 As for the first example, we could have chosen to set the attributes
1307 one by one rather than to rename a package. The reason we explicitly
1308 indicate that @code{Shared} has no sources is so that it can be created
1309 in any directory and we are sure it shares no sources with @code{Build}
1310 or @code{Logging}, which of course would be invalid.
1312 @cindex project qualifier
1313 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1314 This qualifier is optional, but helps convey the message that we do not
1315 intend this project to have sources (@pxref{Qualified Projects} for
1319 @c ---------------------------------------------
1320 @node Global Attributes
1321 @subsection Global Attributes
1322 @c ---------------------------------------------
1325 We have already seen many examples of attributes used to specify a special
1326 option of one of the tools involved in the build process. Most of those
1327 attributes are project specific. That it to say, they only affect the invocation
1328 of tools on the sources of the project where they are defined.
1330 There are a few additional attributes that apply to all projects in a
1331 hierarchy as long as they are defined on the "main" project.
1332 The main project is the project explicitly mentioned on the command-line.
1333 The project hierarchy is the "with"-closure of the main project.
1335 Here is a list of commonly used global attributes:
1338 @item @b{Builder.Global_Configuration_Pragmas}:
1339 @cindex @code{Global_Configuration_Pragmas}
1340 This attribute points to a file that contains configuration pragmas
1341 to use when building executables. These pragmas apply for all
1342 executables build from this project hierarchy. As we have seen before,
1343 additional pragmas can be specified on a per-project basis by setting the
1344 @code{Compiler.Local_Configuration_Pragmas} attribute.
1346 @item @b{Builder.Global_Compilation_Switches}:
1347 @cindex @code{Global_Compilation_Switches}
1348 This attribute is a list of compiler switches to use when compiling any
1349 source file in the project hierarchy. These switches are used in addition
1350 to the ones defined in the @code{Compiler} package, which only apply to
1351 the sources of the corresponding project. This attribute is indexed on
1352 the name of the language.
1356 Using such global capabilities is convenient. It can also lead to unexpected
1357 behavior. Especially when several subsystems are shared among different main
1358 projects and the different global attributes are not
1359 compatible. Note that using aggregate projects can be a safer and more powerful
1360 replacement to global attributes.
1362 @c ---------------------------------------------
1363 @node Scenarios in Projects
1364 @section Scenarios in Projects
1365 @c ---------------------------------------------
1368 Various aspects of the projects can be modified based on @b{scenarios}. These
1369 are user-defined modes that change the behavior of a project. Typical
1370 examples are the setup of platform-specific compiler options, or the use of
1371 a debug and a release mode (the former would activate the generation of debug
1372 information, when the second will focus on improving code optimization).
1374 Let's enhance our example to support a debug and a release modes.The issue is to
1375 let the user choose what kind of system he is building:
1376 use @option{-g} as compiler switches in debug mode and @option{-O2}
1377 in release mode. We will also setup the projects so that we do not share the
1378 same object directory in both modes, otherwise switching from one to the other
1379 might trigger more recompilations than needed or mix objects from the 2 modes.
1381 One naive approach is to create two different project files, say
1382 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1383 attributes as explained in previous sections. This solution does not scale well,
1384 because in presence of multiple projects depending on each other,
1385 you will also have to duplicate the complete hierarchy and adapt the project
1386 files to point to the right copies.
1389 Instead, project files support the notion of scenarios controlled
1390 by external values. Such values can come from several sources (in decreasing
1394 @item @b{Command line}:
1396 When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1397 extra @option{-X} switches to define the external value. In
1398 our case, the command line might look like
1401 gnatmake -Pbuild.gpr -Xmode=debug
1402 or gnatmake -Pbuild.gpr -Xmode=release
1405 @item @b{^Environment variables^Logical names^}:
1406 When the external value does not come from the command line, it can come from
1407 the value of ^environment variables^logical names^ of the appropriate name.
1408 In our case, if ^an environment variable^a logical name^ called "mode"
1409 exist, its value will be taken into account.
1411 @item @b{External function second parameter}
1415 @cindex @code{external}
1416 We now need to get that value in the project. The general form is to use
1417 the predefined function @b{external} which returns the current value of
1418 the external. For instance, we could setup the object directory to point to
1419 either @file{obj/debug} or @file{obj/release} by changing our project to
1421 @smallexample @c projectfile
1423 for Object_Dir use "obj/" & external ("mode", "debug");
1429 The second parameter to @code{external} is optional, and is the default
1430 value to use if "mode" is not set from the command line or the environment.
1432 In order to set the switches according to the different scenarios, other
1433 constructs have to be introduced such as typed variables and case statements.
1435 @cindex typed variable
1436 @cindex case statement
1437 A @b{typed variable} is a variable that
1438 can take only a limited number of values, similar to an enumeration in Ada.
1439 Such a variable can then be used in a @b{case statement} and create conditional
1440 sections in the project. The following example shows how this can be done:
1442 @smallexample @c projectfile
1444 type Mode_Type is ("debug", "release"); -- all possible values
1445 Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1450 for Switches ("Ada") use ("-g");
1452 for Switches ("Ada") use ("-O2");
1459 The project has suddenly grown in size, but has become much more flexible.
1460 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1461 any other value is read from the environment, an error is reported and the
1462 project is considered as invalid.
1464 The @code{Mode} variable is initialized with an external value
1465 defaulting to @code{"debug"}. This default could be omitted and that would
1466 force the user to define the value. Finally, we can use a case statement to set the
1467 switches depending on the scenario the user has chosen.
1469 Most aspects of the projects can depend on scenarios. The notable exception
1470 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1472 Scenarios work the same way with @b{project hierarchies}: you can either
1473 duplicate a variable similar to @code{Mode} in each of the project (as long
1474 as the first argument to @code{external} is always the same and the type is
1475 the same), or simply set the variable in the @file{shared.gpr} project
1476 (@pxref{Sharing Between Projects}).
1478 @c ---------------------------------------------
1479 @node Library Projects
1480 @section Library Projects
1481 @c ---------------------------------------------
1484 So far, we have seen examples of projects that create executables. However,
1485 it is also possible to create libraries instead. A @b{library} is a specific
1486 type of subsystem where, for convenience, objects are grouped together
1487 using system-specific means such as archives or windows DLLs.
1489 Library projects provide a system- and language-independent way of building both @b{static}
1490 and @b{dynamic} libraries. They also support the concept of @b{standalone
1491 libraries} (SAL) which offers two significant properties: the elaboration
1492 (e.g. initialization) of the library is either automatic or very simple;
1494 implementation part of the library implies minimal post-compilation actions on
1495 the complete system and potentially no action at all for the rest of the
1496 system in the case of dynamic SALs.
1498 The GNAT Project Manager takes complete care of the library build, rebuild and
1499 installation tasks, including recompilation of the source files for which
1500 objects do not exist or are not up to date, assembly of the library archive, and
1501 installation of the library (i.e., copying associated source, object and
1502 @file{ALI} files to the specified location).
1505 * Building Libraries::
1506 * Using Library Projects::
1507 * Stand-alone Library Projects::
1508 * Installing a library with project files::
1511 @c ---------------------------------------------
1512 @node Building Libraries
1513 @subsection Building Libraries
1514 @c ---------------------------------------------
1517 Let's enhance our example and transform the @code{logging} subsystem into a
1518 library. In order to do so, a few changes need to be made to @file{logging.gpr}.
1519 A number of specific attributes needs to be defined: at least @code{Library_Name}
1520 and @code{Library_Dir}; in addition, a number of other attributes can be used
1521 to specify specific aspects of the library. For readability, it is also
1522 recommended (although not mandatory), to use the qualifier @code{library} in
1523 front of the @code{project} keyword.
1526 @item @b{Library_Name}:
1527 @cindex @code{Library_Name}
1528 This attribute is the name of the library to be built. There is no
1529 restriction on the name of a library imposed by the project manager, except
1530 for stand-alone libraries whose names must follow the syntax of Ada
1531 identifiers; however, there may be system specific restrictions on the name.
1532 In general, it is recommended to stick to alphanumeric characters (and
1533 possibly single underscores) to help portability.
1535 @item @b{Library_Dir}:
1536 @cindex @code{Library_Dir}
1537 This attribute is the path (absolute or relative) of the directory where
1538 the library is to be installed. In the process of building a library,
1539 the sources are compiled, the object files end up in the explicit or
1540 implicit @code{Object_Dir} directory. When all sources of a library
1541 are compiled, some of the compilation artifacts, including the library itself,
1542 are copied to the library_dir directory. This directory must exists and be
1543 writable. It must also be different from the object directory so that cleanup
1544 activities in the Library_Dir do not affect recompilation needs.
1548 Here is the new version of @file{logging.gpr} that makes it a library:
1550 @smallexample @c projectfile
1551 library project Logging is -- "library" is optional
1552 for Library_Name use "logging"; -- will create "liblogging.a" on Unix
1553 for Object_Dir use "obj";
1554 for Library_Dir use "lib"; -- different from object_dir
1559 Once the above two attributes are defined, the library project is valid and
1560 is enough for building a library with default characteristics.
1561 Other library-related attributes can be used to change the defaults:
1564 @item @b{Library_Kind}:
1565 @cindex @code{Library_Kind}
1566 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1567 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1568 which kind of library should be build (the default is to build a
1569 static library, that is an archive of object files that can potentially
1570 be linked into a static executable). When the library is set to be dynamic,
1571 a separate image is created that will be loaded independently, usually
1572 at the start of the main program execution. Support for dynamic libraries is
1573 very platform specific, for instance on Windows it takes the form of a DLL
1574 while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1575 @file{.so}. Library project files, on the other hand, can be written in
1576 a platform independent way so that the same project file can be used to build
1577 a library on different operating systems.
1579 If you need to build both a static and a dynamic library, it is recommended
1580 use two different object directories, since in some cases some extra code
1581 needs to be generated for the latter. For such cases, one can
1582 either define two different project files, or a single one which uses scenarios
1583 to indicate at the various kinds of library to be build and their
1584 corresponding object_dir.
1586 @cindex @code{Library_ALI_Dir}
1587 @item @b{Library_ALI_Dir}:
1588 This attribute may be specified to indicate the directory where the ALI
1589 files of the library are installed. By default, they are copied into the
1590 @code{Library_Dir} directory, but as for the executables where we have a
1591 separate @code{Exec_Dir} attribute, you might want to put them in a separate
1592 directory since there can be hundreds of them. The same restrictions as for
1593 the @code{Library_Dir} attribute apply.
1595 @cindex @code{Library_Version}
1596 @item @b{Library_Version}:
1597 This attribute is platform dependent, and has no effect on VMS and Windows.
1598 On Unix, it is used only for dynamic libraries as the internal
1599 name of the library (the @code{"soname"}). If the library file name (built
1600 from the @code{Library_Name}) is different from the @code{Library_Version},
1601 then the library file will be a symbolic link to the actual file whose name
1602 will be @code{Library_Version}. This follows the usual installation schemes
1603 for dynamic libraries on many Unix systems.
1605 @smallexample @c projectfile
1609 for Library_Dir use "lib";
1610 for Library_Name use "logging";
1611 for Library_Kind use "dynamic";
1612 for Library_Version use "liblogging.so." & Version;
1618 After the compilation, the directory @file{lib} will contain both a
1619 @file{libdummy.so.1} library and a symbolic link to it called
1622 @cindex @code{Library_GCC}
1623 @item @b{Library_GCC}:
1624 This attribute is the name of the tool to use instead of "gcc" to link shared
1625 libraries. A common use of this attribute is to define a wrapper script that
1626 accomplishes specific actions before calling gcc (which itself is calling the
1627 linker to build the library image).
1629 @item @b{Library_Options}:
1630 @cindex @code{Library_Options}
1631 This attribute may be used to specify additional switches (last switches)
1632 when linking a shared library.
1634 @item @b{Leading_Library_Options}:
1635 @cindex @code{Leading_Library_Options}
1636 This attribute, that is taken into account only by @command{gprbuild}, may be
1637 used to specified leading options (first switches) when linking a shared
1640 @cindex @code{Linker_Options}
1641 @item @b{Linker.Linker_Options}:
1642 This attribute specifies additional switches to be given to the linker when
1643 linking an executable. It is ignored when defined in the main project and
1644 taken into account in all other projects that are imported directly or
1645 indirectly. These switches complement the @code{Linker.Switches}
1646 defined in the main project. This is useful when a particular subsystem
1647 depends on an external library: adding this dependency as a
1648 @code{Linker_Options} in the project of the subsystem is more convenient than
1649 adding it to all the @code{Linker.Switches} of the main projects that depend
1650 upon this subsystem.
1653 @c ---------------------------------------------
1654 @node Using Library Projects
1655 @subsection Using Library Projects
1656 @c ---------------------------------------------
1659 When the builder detects that a project file is a library project file, it
1660 recompiles all sources of the project that need recompilation and rebuild the
1661 library if any of the sources have been recompiled. It then groups all object
1662 files into a single file, which is a shared or a static library. This library
1663 can later on be linked with multiple executables. Note that the use
1664 of shard libraries reduces the size of the final executable and can also reduce
1665 the memory footprint at execution time when the library is shared among several
1668 It is also possible to build @b{multi-language libraries}. When using
1669 @command{gprbuild} as a builder, multi-language library projects allow naturally
1670 the creation of multi-language libraries . @command{gnatmake}, does not try to
1671 compile non Ada sources. However, when the project is multi-language, it will
1672 automatically link all object files found in the object directory, whether or
1673 not they were compiled from an Ada source file. This specific behavior does not
1674 apply to Ada-only projects which only take into account the objects
1675 corresponding to the sources of the project.
1677 A non-library project can import a library project. When the builder is invoked
1678 on the former, the library of the latter is only rebuilt when absolutely
1679 necessary. For instance, if a unit of the
1680 library is not up-to-date but non of the executables need this unit, then the
1681 unit is not recompiled and the library is not reassembled.
1682 For instance, let's assume in our example that logging has the following
1683 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1684 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1685 @file{liblogging} will be rebuilt when compiling all the sources of
1686 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1687 include a @code{"with Log1"}.
1689 To ensure that all the sources in the @code{Logging} library are
1690 up to date, and that all the sources of @code{Build} are also up to date,
1691 the following two commands needs to be used:
1694 gnatmake -Plogging.gpr
1695 gnatmake -Pbuild.gpr
1699 All @file{ALI} files will also be copied from the object directory to the
1700 library directory. To build executables, @command{gnatmake} will use the
1701 library rather than the individual object files.
1704 Library projects can also be useful to describe a library that need to be used
1705 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1706 of the library sources are not available. Such library projects need simply to
1707 use the @code{Externally_Built} attribute as in the example below:
1709 @smallexample @c projectfile
1710 library project Extern_Lib is
1711 for Languages use ("Ada", "C");
1712 for Source_Dirs use ("lib_src");
1713 for Library_Dir use "lib2";
1714 for Library_Kind use "dynamic";
1715 for Library_Name use "l2";
1716 for Externally_Built use "true"; -- <<<<
1721 In the case of externally built libraries, the @code{Object_Dir}
1722 attribute does not need to be specified because it will never be
1725 The main effect of using such an externally built library project is mostly to
1726 affect the linker command in order to reference the desired library. It can
1727 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1728 in the project corresponding to the subsystem needing this external library.
1729 This latter method is more straightforward in simple cases but when several
1730 subsystems depend upon the same external library, finding the proper place
1731 for the @code{Linker.Linker_Options} might not be easy and if it is
1732 not placed properly, the final link command is likely to present ordering issues.
1733 In such a situation, it is better to use the externally built library project
1734 so that all other subsystems depending on it can declare this dependency thanks
1735 to a project @code{with} clause, which in turn will trigger the builder to find
1736 the proper order of libraries in the final link command.
1739 @c ---------------------------------------------
1740 @node Stand-alone Library Projects
1741 @subsection Stand-alone Library Projects
1742 @c ---------------------------------------------
1745 @cindex standalone libraries
1746 A @b{stand-alone library} is a library that contains the necessary code to
1747 elaborate the Ada units that are included in the library. A stand-alone
1748 library is a convenient way to add an Ada subsystem to a more global system
1749 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1750 transparent. However, stand-alone libraries are also useful when the main is in
1751 Ada: they provide a means for minimizing relinking & redeployment of complex
1752 systems when localized changes are made.
1754 The name of a stand-alone library, specified with attribute
1755 @code{Library_Name}, must have the syntax of an Ada identifier.
1757 The most prominent characteristic of a stand-alone library is that it offers a
1758 distinction between interface units and implementation units. Only the former
1759 are visible to units outside the library. A stand-alone library project is thus
1760 characterised by a third attribute, @b{Library_Interface}, in addition to the
1761 two attributes that make a project a Library Project (@code{Library_Name} and
1762 @code{Library_Dir}).
1765 @item @b{Library_Interface}:
1766 @cindex @code{Library_Interface}
1767 This attribute defines an explicit subset of the units of the project.
1768 Projects importing this library project may only "with" units whose sources
1769 are listed in the @code{Library_Interface}. Other sources are considered
1770 implementation units.
1772 @smallexample @c projectfile
1774 for Library_Dir use "lib";
1775 for Library_Name use "loggin";
1776 for Library_Interface use ("lib1", "lib2"); -- unit names
1780 @item @b{Library_Standalone}:
1781 @cindex @code{Library_Standalone}
1782 This attribute defines the kind of standalone library to
1783 build. Values are either @code{standard} (the default), @code{no} or
1784 @code{encapsulated}. When @code{standard} is used the code to elaborate and
1785 finalize the library is embedded, when @code{encapsulated} is used the
1786 library can furthermore only depends on static libraries (including
1787 the GNAT runtime). This attribute can be set to @code{no} to make it clear
1788 that the library should not be standalone in which case the
1789 @code{Library_Interface} should not defined.
1791 @smallexample @c projectfile
1793 for Library_Dir use "lib";
1794 for Library_Name use "loggin";
1795 for Library_Interface use ("lib1", "lib2"); -- unit names
1796 for Library_Standalone use "encapsulated";
1802 In order to include the elaboration code in the stand-alone library, the binder
1803 is invoked on the closure of the library units creating a package whose name
1804 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1805 This binder-generated package includes @b{initialization} and @b{finalization}
1806 procedures whose names depend on the library name (@code{logginginit} and
1807 @code{loggingfinal} in the example). The object corresponding to this package is
1808 included in the library.
1811 @item @b{Library_Auto_Init}:
1812 @cindex @code{Library_Auto_Init}
1813 A dynamic stand-alone Library is automatically initialized
1814 if automatic initialization of Stand-alone Libraries is supported on the
1815 platform and if attribute @b{Library_Auto_Init} is not specified or
1816 is specified with the value "true". A static Stand-alone Library is never
1817 automatically initialized. Specifying "false" for this attribute
1818 prevent automatic initialization.
1820 When a non-automatically initialized stand-alone library is used in an
1821 executable, its initialization procedure must be called before any service of
1822 the library is used. When the main subprogram is in Ada, it may mean that the
1823 initialization procedure has to be called during elaboration of another
1826 @item @b{Library_Dir}:
1827 @cindex @code{Library_Dir}
1828 For a stand-alone library, only the @file{ALI} files of the interface units
1829 (those that are listed in attribute @code{Library_Interface}) are copied to
1830 the library directory. As a consequence, only the interface units may be
1831 imported from Ada units outside of the library. If other units are imported,
1832 the binding phase will fail.
1834 @item @b{Binder.Default_Switches}:
1835 When a stand-alone library is bound, the switches that are specified in
1836 the attribute @b{Binder.Default_Switches ("Ada")} are
1837 used in the call to @command{gnatbind}.
1839 @item @b{Library_Src_Dir}:
1840 @cindex @code{Library_Src_Dir}
1841 This attribute defines the location (absolute or relative to the project
1842 directory) where the sources of the interface units are copied at
1844 These sources includes the specs of the interface units along with the closure
1845 of sources necessary to compile them successfully. That may include bodies and
1846 subunits, when pragmas @code{Inline} are used, or when there is a generic
1847 units in the spec. This directory cannot point to the object directory or
1848 one of the source directories, but it can point to the library directory,
1849 which is the default value for this attribute.
1851 @item @b{Library_Symbol_Policy}:
1852 @cindex @code{Library_Symbol_Policy}
1853 This attribute controls the export of symbols and, on some platforms (like
1854 VMS) that have the notions of major and minor IDs built in the library
1855 files, it controls the setting of these IDs. It is not supported on all
1856 platforms (where it will just have no effect). It may have one of the
1860 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1861 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1862 is not defined, then it is equivalent to policy "autonomous". If there
1863 are exported symbols in the reference symbol file that are not in the
1864 object files of the interfaces, the major ID of the library is increased.
1865 If there are symbols in the object files of the interfaces that are not
1866 in the reference symbol file, these symbols are put at the end of the list
1867 in the newly created symbol file and the minor ID is increased.
1868 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1869 defined. The library will fail to build if the exported symbols in the
1870 object files of the interfaces do not match exactly the symbol in the
1872 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1873 The library will fail to build if there are symbols in the symbol file that
1874 are not in the exported symbols of the object files of the interfaces.
1875 Additional symbols in the object files are not added to the symbol file.
1876 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1877 must designate an existing file in the object directory. This symbol file
1878 is passed directly to the underlying linker without any symbol processing.
1882 @item @b{Library_Reference_Symbol_File}
1883 @cindex @code{Library_Reference_Symbol_File}
1884 This attribute may define the path name of a reference symbol file that is
1885 read when the symbol policy is either "compliant" or "controlled", on
1886 platforms that support symbol control, such as VMS, when building a
1887 stand-alone library. The path may be an absolute path or a path relative
1888 to the project directory.
1890 @item @b{Library_Symbol_File}
1891 @cindex @code{Library_Symbol_File}
1892 This attribute may define the name of the symbol file to be created when
1893 building a stand-alone library when the symbol policy is either "compliant",
1894 "controlled" or "restricted", on platforms that support symbol control,
1895 such as VMS. When symbol policy is "direct", then a file with this name
1896 must exist in the object directory.
1899 @c ---------------------------------------------
1900 @node Installing a library with project files
1901 @subsection Installing a library with project files
1902 @c ---------------------------------------------
1905 When using project files, library installation is part of the library build
1906 process. Thus no further action is needed in order to make use of the
1907 libraries that are built as part of the general application build. A usable
1908 version of the library is installed in the directory specified by the
1909 @code{Library_Dir} attribute of the library project file.
1911 You may want to install a library in a context different from where the library
1912 is built. This situation arises with third party suppliers, who may want
1913 to distribute a library in binary form where the user is not expected to be
1914 able to recompile the library. The simplest option in this case is to provide
1915 a project file slightly different from the one used to build the library, by
1916 using the @code{externally_built} attribute. @ref{Using Library Projects}
1918 @c ---------------------------------------------
1919 @node Project Extension
1920 @section Project Extension
1921 @c ---------------------------------------------
1924 During development of a large system, it is sometimes necessary to use
1925 modified versions of some of the source files, without changing the original
1926 sources. This can be achieved through the @b{project extension} facility.
1928 Suppose for instance that our example @code{Build} project is build every night
1929 for the whole team, in some shared directory. A developer usually need to work
1930 on a small part of the system, and might not want to have a copy of all the
1931 sources and all the object files (mostly because that would require too much
1932 disk space, time to recompile everything). He prefers to be able to override
1933 some of the source files in his directory, while taking advantage of all the
1934 object files generated at night.
1936 Another example can be taken from large software systems, where it is common to have
1937 multiple implementations of a common interface; in Ada terms, multiple
1938 versions of a package body for the same spec. For example, one implementation
1939 might be safe for use in tasking programs, while another might only be used
1940 in sequential applications. This can be modeled in GNAT using the concept
1941 of @emph{project extension}. If one project (the ``child'') @emph{extends}
1942 another project (the ``parent'') then by default all source files of the
1943 parent project are inherited by the child, but the child project can
1944 override any of the parent's source files with new versions, and can also
1945 add new files or remove unnecessary ones.
1946 This facility is the project analog of a type extension in
1947 object-oriented programming. Project hierarchies are permitted (an extending
1948 project may itself be extended), and a project that
1949 extends a project can also import other projects.
1951 A third example is that of using project extensions to provide different
1952 versions of the same system. For instance, assume that a @code{Common}
1953 project is used by two development branches. One of the branches has now
1954 been frozen, and no further change can be done to it or to @code{Common}.
1955 However, the other development branch still needs evolution of @code{Common}.
1956 Project extensions provide a flexible solution to create a new version
1957 of a subsystem while sharing and reusing as much as possible from the original
1960 A project extension inherits implicitly all the sources and objects from the
1961 project it extends. It is possible to create a new version of some of the
1962 sources in one of the additional source dirs of the extending project. Those new
1963 versions hide the original versions. Adding new sources or removing existing
1964 ones is also possible. Here is an example on how to extend the project
1965 @code{Build} from previous examples:
1967 @smallexample @c projectfile
1968 project Work extends "../bld/build.gpr" is
1973 The project after @b{extends} is the one being extended. As usual, it can be
1974 specified using an absolute path, or a path relative to any of the directories
1975 in the project path (@pxref{Project Dependencies}). This project does not
1976 specify source or object directories, so the default value for these attribute
1977 will be used that is to say the current directory (where project @code{Work} is
1978 placed). We can already compile that project with
1985 If no sources have been placed in the current directory, this command
1986 won't do anything, since this project does not change the
1987 sources it inherited from @code{Build}, therefore all the object files
1988 in @code{Build} and its dependencies are still valid and are reused
1991 Suppose we now want to supply an alternate version of @file{pack.adb}
1992 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
1993 We can create the new file Work's current directory (likely
1994 by copying the one from the @code{Build} project and making changes to
1995 it. If new packages are needed at the same time, we simply create
1996 new files in the source directory of the extending project.
1998 When we recompile, @command{gnatmake} will now automatically recompile
1999 this file (thus creating @file{pack.o} in the current directory) and
2000 any file that depends on it (thus creating @file{proc.o}). Finally, the
2001 executable is also linked locally.
2003 Note that we could have obtained the desired behavior using project import
2004 rather than project inheritance. A @code{base} project would contain the
2005 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
2006 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
2007 cannot contain the original version of @file{pack.adb} otherwise there would be
2008 2 versions of the same unit in the closure of the project and this is not
2009 allowed. Generally speaking, it is not recommended to put the spec and the
2010 body of a unit in different projects since this affects their autonomy and
2013 In a project file that extends another project, it is possible to
2014 indicate that an inherited source is @b{not part} of the sources of the
2015 extending project. This is necessary sometimes when a package spec has
2016 been overridden and no longer requires a body: in this case, it is
2017 necessary to indicate that the inherited body is not part of the sources
2018 of the project, otherwise there will be a compilation error
2019 when compiling the spec.
2021 @cindex @code{Excluded_Source_Files}
2022 @cindex @code{Excluded_Source_List_File}
2023 For that purpose, the attribute @b{Excluded_Source_Files} is used.
2024 Its value is a list of file names.
2025 It is also possible to use attribute @code{Excluded_Source_List_File}.
2026 Its value is the path of a text file containing one file name per
2029 @smallexample @c @projectfile
2030 project Work extends "../bld/build.gpr" is
2031 for Source_Files use ("pack.ads");
2032 -- New spec of Pkg does not need a completion
2033 for Excluded_Source_Files use ("pack.adb");
2038 All packages that are not declared in the extending project are inherited from
2039 the project being extended, with their attributes, with the exception of
2040 @code{Linker'Linker_Options} which is never inherited. In particular, an
2041 extending project retains all the switches specified in the project being
2044 At the project level, if they are not declared in the extending project, some
2045 attributes are inherited from the project being extended. They are:
2046 @code{Languages}, @code{Main} (for a root non library project) and
2047 @code{Library_Name} (for a project extending a library project)
2050 * Project Hierarchy Extension::
2053 @c ---------------------------------------------
2054 @node Project Hierarchy Extension
2055 @subsection Project Hierarchy Extension
2056 @c ---------------------------------------------
2059 One of the fundamental restrictions in project extension is the following:
2060 @b{A project is not allowed to import directly or indirectly at the same time an
2061 extending project and one of its ancestors}.
2063 By means of example, consider the following hierarchy of projects.
2066 a.gpr contains package A1
2067 b.gpr, imports a.gpr and contains B1, which depends on A1
2068 c.gpr, imports b.gpr and contains C1, which depends on B1
2072 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2073 create several extending projects:
2076 a_ext.gpr which extends a.gpr, and overrides A1
2077 b_ext.gpr which extends b.gpr and imports a_ext.gpr
2078 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2082 @smallexample @c projectfile
2083 project A_Ext extends "a.gpr" is
2084 for Source_Files use ("a1.adb", "a1.ads");
2088 project B_Ext extends "b.gpr" is
2092 project C_Ext extends "c.gpr" is
2093 for Source_Files use ("c1.adb");
2098 The extension @file{b_ext.gpr} is required, even though we are not overriding
2099 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2100 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2103 When extending a large system spanning multiple projects, it is often
2104 inconvenient to extend every project in the hierarchy that is impacted by a
2105 small change introduced in a low layer. In such cases, it is possible to create
2106 an @b{implicit extension} of entire hierarchy using @b{extends all}
2109 When the project is extended using @code{extends all} inheritance, all projects
2110 that are imported by it, both directly and indirectly, are considered virtually
2111 extended. That is, the project manager creates implicit projects
2112 that extend every project in the hierarchy; all these implicit projects do not
2113 control sources on their own and use the object directory of
2114 the "extending all" project.
2116 It is possible to explicitly extend one or more projects in the hierarchy
2117 in order to modify the sources. These extending projects must be imported by
2118 the "extending all" project, which will replace the corresponding virtual
2119 projects with the explicit ones.
2121 When building such a project hierarchy extension, the project manager will
2122 ensure that both modified sources and sources in implicit extending projects
2123 that depend on them, are recompiled.
2125 Thus, in our example we could create the following projects instead:
2128 a_ext.gpr, extends a.gpr and overrides A1
2129 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2134 @smallexample @c projectfile
2135 project A_Ext extends "a.gpr" is
2136 for Source_Files use ("a1.adb", "a1.ads");
2140 project C_Ext extends all "c.gpr" is
2141 for Source_Files use ("c1.adb");
2146 When building project @file{c_ext.gpr}, the entire modified project space is
2147 considered for recompilation, including the sources of @file{b.gpr} that are
2148 impacted by the changes in @code{A1} and @code{C1}.
2150 @c ---------------------------------------------
2151 @node Aggregate Projects
2152 @section Aggregate Projects
2153 @c ---------------------------------------------
2157 Aggregate projects are an extension of the project paradigm, and are
2158 meant to solve a few specific use cases that cannot be solved directly
2159 using standard projects. This section will go over a few of these use
2160 cases to try and explain what you can use aggregate projects for.
2163 * Building all main programs from a single project tree::
2164 * Building a set of projects with a single command::
2165 * Define a build environment::
2166 * Performance improvements in builder::
2167 * Syntax of aggregate projects::
2168 * package Builder in aggregate projects::
2171 @c -----------------------------------------------------------
2172 @node Building all main programs from a single project tree
2173 @subsection Building all main programs from a single project tree
2174 @c -----------------------------------------------------------
2176 Most often, an application is organized into modules and submodules,
2177 which are very conveniently represented as a project tree or graph
2178 (the root project A @code{with}s the projects for each modules (say B and C),
2179 which in turn @code{with} projects for submodules.
2181 Very often, modules will build their own executables (for testing
2182 purposes for instance), or libraries (for easier reuse in various
2185 However, if you build your project through gnatmake or gprbuild, using
2192 this will only rebuild the main programs of project A, not those of the
2193 imported projects B and C. Therefore you have to spawn several
2194 gnatmake commands, one per project, to build all executables.
2195 This is a little inconvenient, but more importantly is inefficient
2196 (since gnatmake needs to do duplicate work to ensure that sources are
2197 up-to-date, and cannot easily compile things in parallel when using
2200 Also libraries are always rebuild when building a project.
2202 You could therefore define an aggregate project Agg that groups A, B
2203 and C. Then, when you build with
2209 this will build all mains from A, B and C.
2211 @smallexample @c projectfile
2212 aggregate project Agg is
2213 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2217 If B or C do not define any main program (through their Main
2218 attribute), all their sources are build. When you do not group them
2219 in the aggregate project, only those sources that are needed by A
2222 If you add a main to a project P not already explicitly referenced in the
2223 aggregate project, you will need to add "p.gpr" in the list of project
2224 files for the aggregate project, or the main will not be built when
2225 building the aggregate project.
2227 @c ---------------------------------------------------------
2228 @node Building a set of projects with a single command
2229 @subsection Building a set of projects with a single command
2230 @c ---------------------------------------------------------
2232 One other case is when you have multiple applications and libraries
2233 that are build independently from each other (but they can be build in
2234 parallel). For instance, you have a project tree rooted at A, and
2235 another one (which might share some subprojects) rooted at B.
2237 Using only gprbuild, you could do
2244 to build both. But again, gprbuild has to do some duplicate work for
2245 those files that are shared between the two, and cannot truly build
2246 things in parallel efficiently.
2248 If the two projects are really independent, share no sources other
2249 than through a common subproject, and have no source files with a
2250 common basename, you could create a project C that imports A and
2251 B. But these restrictions are often too strong, and one has to build
2252 them independently. An aggregate project does not have these
2253 limitations, and can aggregate two project trees that have common
2257 Aggregate projects can group projects with duplicate file names
2260 This scenario is particularly useful in environment like VxWork 653
2261 where the applications running in the multiple partitions can be build
2262 in parallel through a single gprbuild command. This also works nicely
2266 Aggregate projects can be used to build multiple partitions
2269 @c ---------------------------------------------
2270 @node Define a build environment
2271 @subsection Define a build environment
2272 @c ---------------------------------------------
2274 The environment variables at the time you launch gprbuild or gprbuild
2275 will influence the view these tools have of the project (PATH to find
2276 the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
2277 projects, environment variables that are referenced in project files
2278 through the "external" statement,...). Several command line switches
2279 can be used to override those (-X or -aP), but on some systems and
2280 with some projects, this might make the command line too long, and on
2281 all systems often make it hard to read.
2283 An aggregate project can be used to set the environment for all
2284 projects build through that aggregate. One of the nice aspects is that
2285 you can put the aggregate project under configuration management, and
2286 make sure all your user have a consistent environment when
2287 building. The syntax looks like
2289 @smallexample @c projectfile
2290 aggregate project Agg is
2291 for Project_Files use ("A.gpr", "B.gpr");
2292 for Project_Path use ("../dir1", "../dir1/dir2");
2293 for External ("BUILD") use "PRODUCTION";
2296 for Switches ("Ada") use ("-q");
2301 One of the often requested features in projects is to be able to
2302 reference external variables in @code{with} statements, as in
2304 @smallexample @c projectfile
2305 with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
2306 project MyProject is
2311 For various reasons, this isn't authorized. But using aggregate
2312 projects provide an elegant solution. For instance, you could
2313 use a project file like:
2315 @smallexample @c projectfile
2316 aggregate project Agg is
2317 for Project_Path use (external("SETUP") % "path");
2318 for Project_Files use ("myproject.gpr");
2321 with "prj.gpr"; -- searched on Agg'Project_Path
2322 project MyProject is
2327 @c --------------------------------------------
2328 @node Performance improvements in builder
2329 @subsection Performance improvements in builder
2330 @c --------------------------------------------
2332 The loading of aggregate projects is optimized in gprbuild and
2333 gnatmake, so that all files are searched for only once on the disk
2334 (thus reducing the number of system calls and contributing to faster
2335 compilation times especially on systems with sources on remote
2336 servers). As part of the loading, gprbuild and gnatmake compute how
2337 and where a source file should be compiled, and even if it is found
2338 several times in the aggregated projects it will be compiled only
2341 Since there is no ambiguity as to which switches should be used, files
2342 can be compiled in parallel (through the usual -j switch) and this can
2343 be done while maximizing the use of CPUs (compared to launching
2344 multiple gprbuild and gnatmake commands in parallel).
2346 @c -------------------------------------
2347 @node Syntax of aggregate projects
2348 @subsection Syntax of aggregate projects
2349 @c -------------------------------------
2351 An aggregate project follows the general syntax of project files. The
2352 recommended extension is still @file{.gpr}. However, a special
2353 @code{aggregate} qualifier must be put before the keyword
2356 An aggregate project cannot @code{with} any other project (standard or
2357 aggregate), except an abstract project which can be used to share
2358 attribute values. Building other aggregate projects from an aggregate
2359 project is done through the Project_Files attribute (see below).
2361 An aggregate project does not have any source files directly (only
2362 through other standard projects). Therefore a number of the standard
2363 attributes and packages are forbidden in an aggregate project. Here is the
2364 (non exhaustive) list:
2368 @item Source_Files, Source_List_File and other attributes dealing with
2370 @item Source_Dirs, Exec_Dir and Object_Dir
2371 @item Library_Dir, Library_Name and other library-related attributes
2374 @item Externally_Built
2375 @item Inherit_Source_Path
2376 @item Excluded_Source_Dirs
2377 @item Locally_Removed_Files
2378 @item Excluded_Source_Files
2379 @item Excluded_Source_List_File
2383 The only package that is authorized (albeit optional) is
2384 Builder. Other packages (in particular Compiler, Binder and Linker)
2385 are forbidden. It is an error to have any of these
2386 (and such an error prevents the proper loading of the aggregate
2389 Three new attributes have been created, which can only be used in the
2390 context of aggregate projects:
2393 @item @b{Project_Files}:
2394 @cindex @code{Project_Files}
2396 This attribute is compulsory (or else we are not aggregating any project,
2397 and thus not doing anything). It specifies a list of @file{.gpr} files
2398 that are grouped in the aggregate. The list may be empty. The project
2399 files can be either other aggregate projects, or standard projects. When
2400 grouping standard projects, you can have both the root of a project tree
2401 (and you do not need to specify all its imported projects), and any project
2404 Basically, the idea is to specify all those projects that have
2405 main programs you want to build and link, or libraries you want to
2406 build. You can even specify projects that do not use the Main
2407 attribute nor the @code{Library_*} attributes, and the result will be to
2408 build all their source files (not just the ones needed by other
2411 The file can include paths (absolute or relative). Paths are
2412 relative to the location of the aggregate project file itself (if
2413 you use a base name, we expect to find the .gpr file in the same
2414 directory as the aggregate project file). The extension @file{.gpr} is
2415 mandatory, since this attribute contains file names, not project names.
2417 Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
2418 latter indicates that any subdirectory (recursively) will be
2419 searched for matching files. The latter (@code{"**"}) can only occur at the
2420 last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
2421 not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
2422 to starting with @code{"./**"}.
2424 For now, the pattern @code{"*"} is only allowed in the filename part, not
2425 in the directory part. This is mostly for efficiency reasons to limit the
2426 number of system calls that are needed.
2428 Here are a few valid examples:
2430 @smallexample @c projectfile
2431 for Project_Files use ("a.gpr", "subdir/b.gpr");
2432 -- two specific projects relative to the directory of agg.gpr
2434 for Project_Files use ("**/*.gpr");
2435 -- all projects recursively
2438 @item @b{Project_Path}:
2439 @cindex @code{Project_Path}
2441 This attribute can be used to specify a list of directories in
2442 which to look for project files in @code{with} statements.
2444 When you specify a project in Project_Files
2445 say @code{"x/y/a.gpr"}), and this projects imports a project "b.gpr", only
2446 b.gpr is searched in the project path. a.gpr must be exactly at
2447 <dir of the aggregate>/x/y/a.gpr.
2449 This attribute, however, does not affect the search for the aggregated
2450 project files specified with @code{Project_Files}.
2452 Each aggregate project has its own (that is if agg1.gpr includes
2453 agg2.gpr, they can potentially both have a different project path).
2454 This project path is defined as the concatenation, in that order, of
2455 the current directory, followed by the command line -aP switches,
2456 then the directories from the Project_Path attribute, then the
2457 directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH env.
2458 variables, and finally the predefined directories.
2460 In the example above, agg2.gpr's project path is not influenced by
2461 the attribute agg1'Project_Path, nor is agg1 influenced by
2464 This can potentially lead to errors. In the following example:
2467 +---------------+ +----------------+
2468 | Agg1.gpr |-=--includes--=-->| Agg2.gpr |
2469 | 'project_path| | 'project_path |
2471 +---------------+ +----------------+
2476 +-------+ +---------+
2477 | P.gpr |<---------- withs --------| Q.gpr |
2478 +-------+---------\ +---------+
2483 +-------+ +---------+
2484 | R.gpr | | R'.gpr |
2485 +-------+ +---------+
2488 When looking for p.gpr, both aggregates find the same physical file on
2489 the disk. However, it might happen that with their different project
2490 paths, both aggregate projects would in fact find a different r.gpr.
2491 Since we have a common project (p.gpr) "with"ing two different r.gpr,
2492 this will be reported as an error by the builder.
2494 Directories are relative to the location of the aggregate project file.
2496 Here are a few valid examples:
2498 @smallexample @c projectfile
2499 for Project_Path use ("/usr/local/gpr", "gpr/");
2503 @cindex @code{External}
2505 This attribute can be used to set the value of environment
2506 variables as retrieved through the @code{external} statement
2507 in projects. It does not affect the environment variables
2508 themselves (so for instance you cannot use it to change the value
2509 of your PATH as seen from the spawned compiler).
2511 This attribute affects the external values as seen in the rest of
2512 the aggreate projects, and in the aggregated projects.
2514 The exact value of external a variable comes from one of three
2515 sources (each level overrides the previous levels):
2518 @item An External attribute in aggregate project, for instance
2519 @code{for External ("BUILD_MODE") use "DEBUG"};
2521 @item Environment variables
2523 These override the value given by the attribute, so that
2524 users can override the value set in the (presumably shared
2525 with others in his team) aggregate project.
2527 @item The -X command line switch to gprbuild and gnatmake
2529 This always takes precedence.
2533 This attribute is only taken into account in the main aggregate
2534 project (i.e. the one specified on the command line to gprbuild or
2535 natmake), and ignored in other aggregate projects. It is invalid
2536 in standard projects.
2537 The goal is to have a consistent value in all
2538 projects that are build through the aggregate, which would not
2539 be the case in the diamond case: A groups the aggregate
2540 projects B and C, which both (either directly or indirectly)
2541 build the project P. If B and C could set different values for
2542 the environment variables, we would have two different views of
2543 P, which in particular might impact the list of source files in P.
2547 @c ----------------------------------------------
2548 @node package Builder in aggregate projects
2549 @subsection package Builder in aggregate projects
2550 @c ----------------------------------------------
2552 As we mentioned before, only the package Builder can be specified in
2553 an aggregate project. In this package, only the following attributes
2558 @cindex @code{Switches}
2559 This attribute gives the list of switches to use for the builder
2560 (gprbuild or gnatmake), depending on the language of the main file.
2563 @smallexample @c projectfile
2564 for Switches ("Ada") use ("-d", "-p");
2565 for Switches ("C") use ("-p");
2568 These switches are only read from the main aggregate project (the
2569 one passed on the command line), and ignored in all other aggregate
2570 projects or projects.
2572 It can only contain builder switches, not compiler switches.
2574 @item @b{Global_Compilation_Switches}
2575 @cindex @code{Global_Compilation_Switches}
2577 This attribute gives the list of compiler switches for the various
2578 languages. For instance,
2580 @smallexample @c projectfile
2581 for Global_Compilation_Switches ("Ada") use ("-O1", "-g");
2582 for Global_Compilation_Switches ("C") use ("-O2");
2585 This attribute is only taken into account in the aggregate project
2586 specified on the command line, not in other aggregate projects.
2588 In the projects grouped by that aggregate, the attribute
2589 Builder.Global_Compilation_Switches is also ignored. However, the
2590 attribute Compiler.Default_Switches will be taken into account (but
2591 that of the aggregate have higher priority). The attribute
2592 Compiler.Switches is also taken into account and can be used to
2593 override the switches for a specific file. As a result, it always
2596 The rules are meant to avoid ambiguities when compiling. For
2597 instance, aggregate project Agg groups the projects A and B, that
2598 both depend on C. Here is an extra for all of these projects:
2600 @smallexample @c projectfile
2601 aggregate project Agg is
2602 for Project_Files use ("a.gpr", "b.gpr");
2604 for Global_Compilation_Switches ("Ada") use ("-O2");
2611 for Global_Compilation_Switches ("Ada") use ("-O1");
2616 for Default_Switches ("Ada") use ("-O1", "-g");
2617 for Switches ("a_file1.adb") use ("-O0");
2624 for Default_Switches ("Ada") use ("-O0");
2630 for Default_Switches ("Ada") use ("-O3", "-gnatn");
2631 for Switches ("c_file1.adb") use ("-O0", "-g");
2636 then the following switches are used:
2639 @item all files from project A except a_file1.adb are compiled
2640 with "-O2 -g", since the aggregate project has priority.
2641 @item the file a_file1.adb is compiled with
2642 "-O0", since the Compiler.Switches has priority
2643 @item all files from project B are compiled with
2644 "-O2", since the aggregate project has priority
2645 @item all files from C are compiled with "-O2 -gnatn", except for
2646 c_file1.adb which is compiled with "-O0 -g"
2649 Even though C is seen through two paths (through A and through
2650 B), the switches used by the compiler are unambiguous.
2652 @item @b{Global_Configuration_Pragmas}
2653 @cindex @code{Global_Configuration_Pragmas}
2655 This attribute can be used to specify a file containing
2656 configuration pragmas, to be passed to the compiler. Since we
2657 ignore the package Builder in other aggregate projects and projects,
2658 only those pragmas defined in the main aggregate project will be
2661 Projects can locally add to those by using the
2662 @code{Compiler.Local_Configuration_Pragmas} attribute if they need.
2666 For projects that are build through the aggregate, the package Builder
2667 is ignored, except for the Executable attribute which specifies the
2668 name of the executables resulting from the link of the main programs, and
2669 for the Executable_Suffix.
2671 @c ---------------------------------------------
2672 @node Aggregate Library Projects
2673 @section Aggregate Library Projects
2674 @c ---------------------------------------------
2678 Aggregate library projects make it possible to build a single library
2679 using object files built using other standard or library
2680 projects. This gives the flexibility to describe an application as
2681 having multiple modules (a GUI, database access, ...) using different
2682 project files (so possibly built with different compiler options) and
2683 yet create a single library (static or relocatable) out of the
2684 corresponding object files.
2687 * Building aggregate library projects::
2688 * Syntax of aggregate library projects::
2691 @c ---------------------------------------------
2692 @node Building aggregate library projects
2693 @subsection Building aggregate library projects
2694 @c ---------------------------------------------
2696 For example, we can define an aggregate project Agg that groups A, B
2699 @smallexample @c projectfile
2700 aggregate library project Agg is
2701 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2702 for Library_Name use ("agg");
2703 for Library_Dir use ("lagg");
2707 Then, when you build with:
2713 This will build all units from projects A, B and C and will create a
2714 static library named @file{libagg.a} into the @file{lagg}
2715 directory. An aggregate library project has the same set of
2716 restriction as a standard library project.
2718 Note that a shared aggregate library project cannot aggregates a
2719 static library project. In platforms where a compiler option is
2720 required to create relocatable object files, a Builder package in the
2721 aggregate library project may be used:
2723 @smallexample @c projectfile
2724 aggregate library project Agg is
2725 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2726 for Library_Name use ("agg");
2727 for Library_Dir use ("lagg");
2728 for Library_Kind use "relocatable";
2731 for Global_Compilation_Switches ("Ada") use ("-fPIC");
2736 With the above aggregate library Builder package, the @code{-fPIC}
2737 option will be passed to the compiler when building any source code
2738 from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}.
2740 @c ---------------------------------------------
2741 @node Syntax of aggregate library projects
2742 @subsection Syntax of aggregate library projects
2743 @c ---------------------------------------------
2745 An aggregate library project follows the general syntax of project
2746 files. The recommended extension is still @file{.gpr}. However, a special
2747 @code{aggregate library} qualifier must be put before the keyword
2750 An aggregate library project cannot @code{with} any other project
2751 (standard or aggregate), except an abstract project which can be used
2752 to share attribute values.
2754 An aggregate library project does not have any source files directly (only
2755 through other standard projects). Therefore a number of the standard
2756 attributes and packages are forbidden in an aggregate library
2757 project. Here is the (non exhaustive) list:
2761 @item Source_Files, Source_List_File and other attributes dealing with
2763 @item Source_Dirs, Exec_Dir and Object_Dir
2766 @item Externally_Built
2767 @item Inherit_Source_Path
2768 @item Excluded_Source_Dirs
2769 @item Locally_Removed_Files
2770 @item Excluded_Source_Files
2771 @item Excluded_Source_List_File
2775 The only package that is authorized (albeit optional) is Builder.
2777 The Project_Files attribute (See @pxref{Aggregate Projects}) is used to
2778 described the aggregated projects whose object files have to be
2779 included into the aggregate library.
2781 @c ---------------------------------------------
2782 @node Project File Reference
2783 @section Project File Reference
2784 @c ---------------------------------------------
2787 This section describes the syntactic structure of project files, the various
2788 constructs that can be used. Finally, it ends with a summary of all available
2792 * Project Declaration::
2793 * Qualified Projects::
2798 * Typed String Declaration::
2804 @c ---------------------------------------------
2805 @node Project Declaration
2806 @subsection Project Declaration
2807 @c ---------------------------------------------
2810 Project files have an Ada-like syntax. The minimal project file is:
2812 @smallexample @c projectfile
2820 The identifier @code{Empty} is the name of the project.
2821 This project name must be present after the reserved
2822 word @code{end} at the end of the project file, followed by a semi-colon.
2824 @b{Identifiers} (i.e.@: the user-defined names such as project or variable names)
2825 have the same syntax as Ada identifiers: they must start with a letter,
2826 and be followed by zero or more letters, digits or underscore characters;
2827 it is also illegal to have two underscores next to each other. Identifiers
2828 are always case-insensitive ("Name" is the same as "name").
2831 simple_name ::= identifier
2832 name ::= simple_name @{ . simple_name @}
2836 @b{Strings} are used for values of attributes or as indexes for these
2837 attributes. They are in general case sensitive, except when noted
2838 otherwise (in particular, strings representing file names will be case
2839 insensitive on some systems, so that "file.adb" and "File.adb" both
2840 represent the same file).
2842 @b{Reserved words} are the same as for standard Ada 95, and cannot
2843 be used for identifiers. In particular, the following words are currently
2844 used in project files, but others could be added later on. In bold are the
2845 extra reserved words in project files: @code{all, at, case, end, for, is,
2846 limited, null, others, package, renames, type, use, when, with, @b{extends},
2847 @b{external}, @b{project}}.
2849 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2850 hyphens through the end of the line.
2852 A project may be an @b{independent project}, entirely defined by a single
2853 project file. Any source file in an independent project depends only
2854 on the predefined library and other source files in the same project.
2855 But a project may also depend on other projects, either by importing them
2856 through @b{with clauses}, or by @b{extending} at most one other project. Both
2857 types of dependency can be used in the same project.
2859 A path name denotes a project file. It can be absolute or relative.
2860 An absolute path name includes a sequence of directories, in the syntax of
2861 the host operating system, that identifies uniquely the project file in the
2862 file system. A relative path name identifies the project file, relative
2863 to the directory that contains the current project, or relative to a
2864 directory listed in the environment variables ADA_PROJECT_PATH and
2865 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2866 operating system are case sensitive. As a special case, the directory
2867 separator can always be "/" even on Windows systems, so that project files
2868 can be made portable across architectures.
2869 The syntax of the environment variable ADA_PROJECT_PATH and
2870 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2871 semicolons on Windows.
2873 A given project name can appear only once in a context clause.
2875 It is illegal for a project imported by a context clause to refer, directly
2876 or indirectly, to the project in which this context clause appears (the
2877 dependency graph cannot contain cycles), except when one of the with clause
2878 in the cycle is a @b{limited with}.
2879 @c ??? Need more details here
2881 @smallexample @c projectfile
2882 with "other_project.gpr";
2883 project My_Project extends "extended.gpr" is
2888 These dependencies form a @b{directed graph}, potentially cyclic when using
2889 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
2892 A project's @b{immediate sources} are the source files directly defined by
2893 that project, either implicitly by residing in the project source directories,
2894 or explicitly through any of the source-related attributes.
2895 More generally, a project sources are the immediate sources of the project
2896 together with the immediate sources (unless overridden) of any
2897 project on which it depends directly or indirectly.
2899 A @b{project hierarchy} can be created, where projects are children of
2900 other projects. The name of such a child project must be @code{Parent.Child},
2901 where @code{Parent} is the name of the parent project. In particular, this
2902 makes all @code{with} clauses of the parent project automatically visible
2903 in the child project.
2906 project ::= context_clause project_declaration
2908 context_clause ::= @{with_clause@}
2909 with_clause ::= @i{with} path_name @{ , path_name @} ;
2910 path_name ::= string_literal
2912 project_declaration ::= simple_project_declaration | project_extension
2913 simple_project_declaration ::=
2914 @i{project} @i{<project_>}name @i{is}
2915 @{declarative_item@}
2916 @i{end} <project_>simple_name;
2919 @c ---------------------------------------------
2920 @node Qualified Projects
2921 @subsection Qualified Projects
2922 @c ---------------------------------------------
2925 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
2926 is identifiers or reserved words, to qualify the project.
2927 The current list of qualifiers is:
2930 @item @b{abstract}: qualifies a project with no sources. Such a
2931 project must either have no declaration of attributes @code{Source_Dirs},
2932 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
2933 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
2934 as empty. If it extends another project, the project it extends must also be a
2935 qualified abstract project.
2936 @item @b{standard}: a standard project is a non library project with sources.
2937 This is the default (implicit) qualifier.
2938 @item @b{aggregate}: a project whose sources are aggregated from other
2940 @item @b{aggregate library}: a library whose sources are aggregated
2941 from other project or library project files.
2942 @item @b{library}: a library project must declare both attributes
2943 @code{Library_Name} and @code{Library_Dir}.
2944 @item @b{configuration}: a configuration project cannot be in a project tree.
2945 It describes compilers and other tools to @code{gprbuild}.
2948 @c ---------------------------------------------
2950 @subsection Declarations
2951 @c ---------------------------------------------
2954 Declarations introduce new entities that denote types, variables, attributes,
2955 and packages. Some declarations can only appear immediately within a project
2956 declaration. Others can appear within a project or within a package.
2959 declarative_item ::= simple_declarative_item
2960 | typed_string_declaration
2961 | package_declaration
2963 simple_declarative_item ::= variable_declaration
2964 | typed_variable_declaration
2965 | attribute_declaration
2969 empty_declaration ::= @i{null} ;
2973 An empty declaration is allowed anywhere a declaration is allowed. It has
2976 @c ---------------------------------------------
2978 @subsection Packages
2979 @c ---------------------------------------------
2982 A project file may contain @b{packages}, that group attributes (typically
2983 all the attributes that are used by one of the GNAT tools).
2985 A package with a given name may only appear once in a project file.
2986 The following packages are currently supported in project files
2987 (See @pxref{Attributes} for the list of attributes that each can contain).
2991 This package specifies characteristics useful when invoking the binder either
2992 directly via the @command{gnat} driver or when using a builder such as
2993 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
2995 This package specifies the compilation options used when building an
2996 executable or a library for a project. Most of the options should be
2997 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
2998 but there are some general options that should be defined in this
2999 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
3002 This package specifies the options used when calling the checking tool
3003 @command{gnatcheck} via the @command{gnat} driver. Its attribute
3004 @b{Default_Switches} has the same semantics as for the package
3005 @code{Builder}. The first string should always be @code{-rules} to specify
3006 that all the other options belong to the @code{-rules} section of the
3007 parameters to @command{gnatcheck}.
3009 This package specifies the compilation options used by the compiler for
3010 each languages. @xref{Tools Options in Project Files}.
3011 @item Cross_Reference
3012 This package specifies the options used when calling the library tool
3013 @command{gnatxref} via the @command{gnat} driver. Its attributes
3014 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3015 package @code{Builder}.
3017 This package specifies the options used when calling the tool
3018 @command{gnatelim} via the @command{gnat} driver. Its attributes
3019 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3020 package @code{Builder}.
3022 This package specifies the options used when calling the search tool
3023 @command{gnatfind} via the @command{gnat} driver. Its attributes
3024 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3025 package @code{Builder}.
3027 This package the options to use when invoking @command{gnatls} via the
3028 @command{gnat} driver.
3030 This package specifies the options used when calling the tool
3031 @command{gnatstub} via the @command{gnat} driver. Its attributes
3032 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3033 package @code{Builder}.
3035 This package specifies the options used when starting an integrated
3036 development environment, for instance @command{GPS} or @command{Gnatbench}.
3037 @xref{The Development Environments}.
3039 This package specifies the options used by the linker.
3040 @xref{Main Subprograms}.
3042 @cindex Makefile package in projects
3043 This package is used by the GPS plugin Makefile.py. See the documentation
3044 in that plugin (from GPS: /Tools/Plug-ins).
3046 This package specifies the options used when calling the tool
3047 @command{gnatmetric} via the @command{gnat} driver. Its attributes
3048 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3049 package @code{Builder}.
3051 This package specifies the naming conventions that apply
3052 to the source files in a project. In particular, these conventions are
3053 used to automatically find all source files in the source directories,
3054 or given a file name to find out its language for proper processing.
3055 @xref{Naming Schemes}.
3056 @item Pretty_Printer
3057 This package specifies the options used when calling the formatting tool
3058 @command{gnatpp} via the @command{gnat} driver. Its attributes
3059 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3060 package @code{Builder}.
3062 This package specifies the options used when calling the tool
3063 @command{gnatstack} via the @command{gnat} driver. Its attributes
3064 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3065 package @code{Builder}.
3067 This package specifies the options used when calling the tool
3068 @command{gnatsync} via the @command{gnat} driver.
3072 In its simplest form, a package may be empty:
3074 @smallexample @c projectfile
3084 A package may contain @b{attribute declarations},
3085 @b{variable declarations} and @b{case constructions}, as will be
3088 When there is ambiguity between a project name and a package name,
3089 the name always designates the project. To avoid possible confusion, it is
3090 always a good idea to avoid naming a project with one of the
3091 names allowed for packages or any name that starts with @code{gnat}.
3093 A package can also be defined by a @b{renaming declaration}. The new package
3094 renames a package declared in a different project file, and has the same
3095 attributes as the package it renames. The name of the renamed package
3096 must be the same as the name of the renaming package. The project must
3097 contain a package declaration with this name, and the project
3098 must appear in the context clause of the current project, or be its parent
3099 project. It is not possible to add or override attributes to the renaming
3100 project. If you need to do so, you should use an @b{extending declaration}
3103 Packages that are renamed in other project files often come from project files
3104 that have no sources: they are just used as templates. Any modification in the
3105 template will be reflected automatically in all the project files that rename
3106 a package from the template. This is a very common way to share settings
3109 Finally, a package can also be defined by an @b{extending declaration}. This is
3110 similar to a @b{renaming declaration}, except that it is possible to add or
3111 override attributes.
3114 package_declaration ::= package_spec | package_renaming | package_extension
3116 @i{package} @i{<package_>}simple_name @i{is}
3117 @{simple_declarative_item@}
3118 @i{end} package_identifier ;
3119 package_renaming ::==
3120 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
3121 package_extension ::==
3122 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
3123 @{simple_declarative_item@}
3124 @i{end} package_identifier ;
3127 @c ---------------------------------------------
3129 @subsection Expressions
3130 @c ---------------------------------------------
3133 An expression is any value that can be assigned to an attribute or a
3134 variable. It is either a literal value, or a construct requiring runtime
3135 computation by the project manager. In a project file, the computed value of
3136 an expression is either a string or a list of strings.
3138 A string value is one of:
3140 @item A literal string, for instance @code{"comm/my_proj.gpr"}
3141 @item The name of a variable that evaluates to a string (@pxref{Variables})
3142 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
3143 @item An external reference (@pxref{External Values})
3144 @item A concatenation of the above, as in @code{"prefix_" & Var}.
3149 A list of strings is one of the following:
3152 @item A parenthesized comma-separated list of zero or more string expressions, for
3153 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
3154 @item The name of a variable that evaluates to a list of strings
3155 @item The name of an attribute that evaluates to a list of strings
3156 @item A concatenation of a list of strings and a string (as defined above), for
3157 instance @code{("A", "B") & "C"}
3158 @item A concatenation of two lists of strings
3163 The following is the grammar for expressions
3166 string_literal ::= "@{string_element@}" -- Same as Ada
3167 string_expression ::= string_literal
3170 | attribute_reference
3171 | ( string_expression @{ & string_expression @} )
3172 string_list ::= ( string_expression @{ , string_expression @} )
3173 | @i{string_variable}_name
3174 | @i{string_}attribute_reference
3175 term ::= string_expression | string_list
3176 expression ::= term @{ & term @} -- Concatenation
3180 Concatenation involves strings and list of strings. As soon as a list of
3181 strings is involved, the result of the concatenation is a list of strings. The
3182 following Ada declarations show the existing operators:
3184 @smallexample @c ada
3185 function "&" (X : String; Y : String) return String;
3186 function "&" (X : String_List; Y : String) return String_List;
3187 function "&" (X : String_List; Y : String_List) return String_List;
3191 Here are some specific examples:
3193 @smallexample @c projectfile
3195 List := () & File_Name; -- One string in this list
3196 List2 := List & (File_Name & ".orig"); -- Two strings
3197 Big_List := List & Lists2; -- Three strings
3198 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
3202 @c ---------------------------------------------
3203 @node External Values
3204 @subsection External Values
3205 @c ---------------------------------------------
3208 An external value is an expression whose value is obtained from the command
3209 that invoked the processing of the current project file (typically a
3210 gnatmake or gprbuild command).
3212 There are two kinds of external values, one that returns a single string, and
3213 one that returns a string list.
3215 The syntax of a single string external value is:
3218 external_value ::= @i{external} ( string_literal [, string_literal] )
3222 The first string_literal is the string to be used on the command line or
3223 in the environment to specify the external value. The second string_literal,
3224 if present, is the default to use if there is no specification for this
3225 external value either on the command line or in the environment.
3227 Typically, the external value will either exist in the
3228 ^environment variables^logical name^
3229 or be specified on the command line through the
3230 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
3231 are specified, then the command line value is used, so that a user can more
3232 easily override the value.
3234 The function @code{external} always returns a string. It is an error if the
3235 value was not found in the environment and no default was specified in the
3236 call to @code{external}.
3238 An external reference may be part of a string expression or of a string
3239 list expression, and can therefore appear in a variable declaration or
3240 an attribute declaration.
3242 Most of the time, this construct is used to initialize typed variables, which
3243 are then used in @b{case} statements to control the value assigned to
3244 attributes in various scenarios. Thus such variables are often called
3245 @b{scenario variables}.
3247 The syntax for a string list external value is:
3250 external_value ::= @i{external_as_list} ( string_literal , string_literal )
3254 The first string_literal is the string to be used on the command line or
3255 in the environment to specify the external value. The second string_literal is
3256 the separator between each component of the string list.
3258 If the external value does not exist in the environment or on the command line,
3259 the result is an empty list. This is also the case, if the separator is an
3260 empty string or if the external value is only one separator.
3262 Any separator at the beginning or at the end of the external value is
3263 discarded. Then, if there is no separator in the external value, the result is
3264 a string list with only one string. Otherwise, any string between the beginning
3265 and the first separator, between two consecutive separators and between the
3266 last separator and the end are components of the string list.
3269 @i{external_as_list} ("SWITCHES", ",")
3273 If the external value is "-O2,-g", the result is ("-O2", "-g").
3275 If the external value is ",-O2,-g,", the result is also ("-O2", "-g").
3277 if the external value is "-gnav", the result is ("-gnatv").
3279 If the external value is ",,", the result is ("").
3281 If the external value is ",", the result is (), the empty string list.
3283 @c ---------------------------------------------
3284 @node Typed String Declaration
3285 @subsection Typed String Declaration
3286 @c ---------------------------------------------
3289 A @b{type declaration} introduces a discrete set of string literals.
3290 If a string variable is declared to have this type, its value
3291 is restricted to the given set of literals. These are the only named
3292 types in project files. A string type may only be declared at the project
3293 level, not inside a package.
3296 typed_string_declaration ::=
3297 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
3301 The string literals in the list are case sensitive and must all be different.
3302 They may include any graphic characters allowed in Ada, including spaces.
3303 Here is an example of a string type declaration:
3305 @smallexample @c projectfile
3306 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
3310 Variables of a string type are called @b{typed variables}; all other
3311 variables are called @b{untyped variables}. Typed variables are
3312 particularly useful in @code{case} constructions, to support conditional
3313 attribute declarations. (@pxref{Case Statements}).
3315 A string type may be referenced by its name if it has been declared in the same
3316 project file, or by an expanded name whose prefix is the name of the project
3317 in which it is declared.
3319 @c ---------------------------------------------
3321 @subsection Variables
3322 @c ---------------------------------------------
3325 @b{Variables} store values (strings or list of strings) and can appear
3326 as part of an expression. The declaration of a variable creates the
3327 variable and assigns the value of the expression to it. The name of the
3328 variable is available immediately after the assignment symbol, if you
3329 need to reuse its old value to compute the new value. Before the completion
3330 of its first declaration, the value of a variable defaults to the empty
3333 A @b{typed} variable can be used as part of a @b{case} expression to
3334 compute the value, but it can only be declared once in the project file,
3335 so that all case statements see the same value for the variable. This
3336 provides more consistency and makes the project easier to understand.
3337 The syntax for its declaration is identical to the Ada syntax for an
3338 object declaration. In effect, a typed variable acts as a constant.
3340 An @b{untyped} variable can be declared and overridden multiple times
3341 within the same project. It is declared implicitly through an Ada
3342 assignment. The first declaration establishes the kind of the variable
3343 (string or list of strings) and successive declarations must respect
3344 the initial kind. Assignments are executed in the order in which they
3345 appear, so the new value replaces the old one and any subsequent reference
3346 to the variable uses the new value.
3348 A variable may be declared at the project file level, or within a package.
3351 typed_variable_declaration ::=
3352 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
3353 variable_declaration ::= @i{<variable_>}simple_name := expression;
3357 Here are some examples of variable declarations:
3359 @smallexample @c projectfile
3361 This_OS : OS := external ("OS"); -- a typed variable declaration
3362 That_OS := "GNU/Linux"; -- an untyped variable declaration
3364 Name := "readme.txt";
3365 Save_Name := Name & ".saved";
3368 List_With_One_Element := ("-gnaty");
3369 List_With_Two_Elements := List_With_One_Element & "-gnatg";
3370 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
3375 A @b{variable reference} may take several forms:
3378 @item The simple variable name, for a variable in the current package (if any)
3379 or in the current project
3380 @item An expanded name, whose prefix is a context name.
3385 A @b{context} may be one of the following:
3388 @item The name of an existing package in the current project
3389 @item The name of an imported project of the current project
3390 @item The name of an ancestor project (i.e., a project extended by the current
3391 project, either directly or indirectly)
3392 @item An expanded name whose prefix is an imported/parent project name, and
3393 whose selector is a package name in that project.
3396 @c ---------------------------------------------
3398 @subsection Attributes
3399 @c ---------------------------------------------
3402 A project (and its packages) may have @b{attributes} that define
3403 the project's properties. Some attributes have values that are strings;
3404 others have values that are string lists.
3407 attribute_declaration ::=
3408 simple_attribute_declaration | indexed_attribute_declaration
3409 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
3410 indexed_attribute_declaration ::=
3411 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
3412 attribute_designator ::=
3413 @i{<simple_attribute_>}simple_name
3414 | @i{<indexed_attribute_>}simple_name ( string_literal )
3418 There are two categories of attributes: @b{simple attributes}
3419 and @b{indexed attributes}.
3420 Each simple attribute has a default value: the empty string (for string
3421 attributes) and the empty list (for string list attributes).
3422 An attribute declaration defines a new value for an attribute, and overrides
3423 the previous value. The syntax of a simple attribute declaration is similar to
3424 that of an attribute definition clause in Ada.
3426 Some attributes are indexed. These attributes are mappings whose
3427 domain is a set of strings. They are declared one association
3428 at a time, by specifying a point in the domain and the corresponding image
3430 Like untyped variables and simple attributes, indexed attributes
3431 may be declared several times. Each declaration supplies a new value for the
3432 attribute, and replaces the previous setting.
3434 Here are some examples of attribute declarations:
3436 @smallexample @c projectfile
3437 -- simple attributes
3438 for Object_Dir use "objects";
3439 for Source_Dirs use ("units", "test/drivers");
3441 -- indexed attributes
3442 for Body ("main") use "Main.ada";
3443 for Switches ("main.ada") use ("-v", "-gnatv");
3444 for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
3446 -- indexed attributes copy (from package Builder in project Default)
3447 -- The package name must always be specified, even if it is the current
3449 for Default_Switches use Default.Builder'Default_Switches;
3453 Attributes references may be appear anywhere in expressions, and are used
3454 to retrieve the value previously assigned to the attribute. If an attribute
3455 has not been set in a given package or project, its value defaults to the
3456 empty string or the empty list.
3459 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
3460 attribute_prefix ::= @i{project}
3461 | @i{<project_>}simple_name
3462 | package_identifier
3463 | @i{<project_>}simple_name . package_identifier
3469 @smallexample @c projectfile
3471 Naming'Dot_Replacement
3472 Imported_Project'Source_Dirs
3473 Imported_Project.Naming'Casing
3474 Builder'Default_Switches ("Ada")
3478 The prefix of an attribute may be:
3481 @item @code{project} for an attribute of the current project
3482 @item The name of an existing package of the current project
3483 @item The name of an imported project
3484 @item The name of a parent project that is extended by the current project
3485 @item An expanded name whose prefix is imported/parent project name,
3486 and whose selector is a package name
3491 Legal attribute names are listed below, including the package in
3492 which they must be declared. These names are case-insensitive. The
3493 semantics for the attributes is explained in great details in other sections.
3495 The column @emph{index} indicates whether the attribute is an indexed attribute,
3496 and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the
3497 system (file). The text is between brackets ([]) if the index is optional.
3499 @multitable @columnfractions .3 .1 .2 .4
3500 @headitem Attribute Name @tab Value @tab Package @tab Index
3501 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
3502 @item Name @tab string @tab - @tab (Read-only, name of project)
3503 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
3504 @item Source_Files @tab list @tab - @tab -
3505 @item Source_Dirs @tab list @tab - @tab -
3506 @item Source_List_File @tab string @tab - @tab -
3507 @item Locally_Removed_Files @tab list @tab - @tab -
3508 @item Excluded_Source_Files @tab list @tab - @tab -
3509 @item Object_Dir @tab string @tab - @tab -
3510 @item Exec_Dir @tab string @tab - @tab -
3511 @item Excluded_Source_Dirs @tab list @tab - @tab -
3512 @item Excluded_Source_Files @tab list @tab - @tab -
3513 @item Excluded_Source_List_File @tab list @tab - @tab -
3514 @item Inherit_Source_Path @tab list @tab - @tab insensitive
3515 @item Languages @tab list @tab - @tab -
3516 @item Main @tab list @tab - @tab -
3517 @item Main_Language @tab string @tab - @tab -
3518 @item Externally_Built @tab string @tab - @tab -
3519 @item Roots @tab list @tab - @tab file
3521 Library-related attributes @tab @tab @tab @pxref{Library Projects}
3522 @item Library_Dir @tab string @tab - @tab -
3523 @item Library_Name @tab string @tab - @tab -
3524 @item Library_Kind @tab string @tab - @tab -
3525 @item Library_Version @tab string @tab - @tab -
3526 @item Library_Interface @tab string @tab - @tab -
3527 @item Library_Auto_Init @tab string @tab - @tab -
3528 @item Library_Options @tab list @tab - @tab -
3529 @item Leading_Library_Options @tab list @tab - @tab -
3530 @item Library_Src_Dir @tab string @tab - @tab -
3531 @item Library_ALI_Dir @tab string @tab - @tab -
3532 @item Library_GCC @tab string @tab - @tab -
3533 @item Library_Symbol_File @tab string @tab - @tab -
3534 @item Library_Symbol_Policy @tab string @tab - @tab -
3535 @item Library_Reference_Symbol_File @tab string @tab - @tab -
3536 @item Interfaces @tab list @tab - @tab -
3538 Naming @tab @tab @tab @pxref{Naming Schemes}
3539 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
3540 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
3541 @item Separate_Suffix @tab string @tab Naming @tab -
3542 @item Casing @tab string @tab Naming @tab -
3543 @item Dot_Replacement @tab string @tab Naming @tab -
3544 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
3545 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
3546 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
3547 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
3549 Building @tab @tab @tab @pxref{Switches and Project Files}
3550 @item Default_Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE @tab insensitive (language name)
3551 @item Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack @tab [file] (file name)
3552 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
3553 @item Local_Config_File @tab string @tab insensitive @tab -
3554 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
3555 @item Global_Compilation_Switches @tab list @tab Builder @tab language
3556 @item Executable @tab string @tab Builder @tab [file]
3557 @item Executable_Suffix @tab string @tab Builder @tab -
3558 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
3560 IDE (used and created by GPS) @tab @tab @tab
3561 @item Remote_Host @tab string @tab IDE @tab -
3562 @item Program_Host @tab string @tab IDE @tab -
3563 @item Communication_Protocol @tab string @tab IDE @tab -
3564 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
3565 @item Debugger_Command @tab string @tab IDE @tab -
3566 @item Gnatlist @tab string @tab IDE @tab -
3567 @item Gnat @tab string @tab IDE @tab -
3568 @item VCS_Kind @tab string @tab IDE @tab -
3569 @item VCS_File_Check @tab string @tab IDE @tab -
3570 @item VCS_Log_Check @tab string @tab IDE @tab -
3571 @item Documentation_Dir @tab string @tab IDE @tab -
3573 Configuration files @tab @tab @tab See gprbuild manual
3574 @item Default_Language @tab string @tab - @tab -
3575 @item Run_Path_Option @tab list @tab - @tab -
3576 @item Run_Path_Origin @tab string @tab - @tab -
3577 @item Separate_Run_Path_Options @tab string @tab - @tab -
3578 @item Toolchain_Version @tab string @tab - @tab insensitive
3579 @item Toolchain_Description @tab string @tab - @tab insensitive
3580 @item Object_Generated @tab string @tab - @tab insensitive
3581 @item Objects_Linked @tab string @tab - @tab insensitive
3582 @item Target @tab string @tab - @tab -
3583 @item Library_Builder @tab string @tab - @tab -
3584 @item Library_Support @tab string @tab - @tab -
3585 @item Archive_Builder @tab list @tab - @tab -
3586 @item Archive_Builder_Append_Option @tab list @tab - @tab -
3587 @item Archive_Indexer @tab list @tab - @tab -
3588 @item Archive_Suffix @tab string @tab - @tab -
3589 @item Library_Partial_Linker @tab list @tab - @tab -
3590 @item Shared_Library_Prefix @tab string @tab - @tab -
3591 @item Shared_Library_Suffix @tab string @tab - @tab -
3592 @item Symbolic_Link_Supported @tab string @tab - @tab -
3593 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
3594 @item Library_Auto_Init_Supported @tab string @tab - @tab -
3595 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
3596 @item Library_Version_Switches @tab list @tab - @tab -
3597 @item Library_Install_Name_Option @tab string @tab - @tab -
3598 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
3599 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
3600 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
3601 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
3602 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3603 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3604 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
3605 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
3606 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
3607 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
3608 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
3609 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitive (language)
3610 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
3611 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
3612 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
3613 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
3614 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
3615 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3616 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3617 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
3618 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3619 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3620 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
3621 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
3622 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
3623 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
3624 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
3625 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
3626 @item Prefix @tab string @tab Binder @tab insensitive (language)
3627 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
3628 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
3629 @item Linker_Options @tab list @tab Linker @tab -
3630 @item Leading_Switches @tab list @tab Linker @tab -
3631 @item Map_File_Options @tab string @tab Linker @tab -
3632 @item Executable_Switches @tab list @tab Linker @tab -
3633 @item Lib_Dir_Switch @tab string @tab Linker @tab -
3634 @item Lib_Name_Switch @tab string @tab Linker @tab -
3635 @item Max_Command_Line_Length @tab string @tab Linker @tab -
3636 @item Response_File_Format @tab string @tab Linker @tab -
3637 @item Response_File_Switches @tab list @tab Linker @tab -
3640 @c ---------------------------------------------
3641 @node Case Statements
3642 @subsection Case Statements
3643 @c ---------------------------------------------
3646 A @b{case} statement is used in a project file to effect conditional
3647 behavior. Through this statement, you can set the value of attributes
3648 and variables depending on the value previously assigned to a typed
3651 All choices in a choice list must be distinct. Unlike Ada, the choice
3652 lists of all alternatives do not need to include all values of the type.
3653 An @code{others} choice must appear last in the list of alternatives.
3655 The syntax of a @code{case} construction is based on the Ada case statement
3656 (although the @code{null} statement for empty alternatives is optional).
3658 The case expression must be a typed string variable, whose value is often
3659 given by an external reference (@pxref{External Values}).
3661 Each alternative starts with the reserved word @code{when}, either a list of
3662 literal strings separated by the @code{"|"} character or the reserved word
3663 @code{others}, and the @code{"=>"} token.
3664 Each literal string must belong to the string type that is the type of the
3666 After each @code{=>}, there are zero or more statements. The only
3667 statements allowed in a case construction are other case statements,
3668 attribute declarations and variable declarations. String type declarations and
3669 package declarations are not allowed. Variable declarations are restricted to
3670 variables that have already been declared before the case construction.
3674 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
3677 @i{when} discrete_choice_list =>
3679 | attribute_declaration
3680 | variable_declaration
3681 | empty_declaration@}
3683 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
3687 Here is a typical example:
3689 @smallexample @c projectfile
3692 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
3693 OS : OS_Type := external ("OS", "GNU/Linux");
3697 when "GNU/Linux" | "Unix" =>
3698 for Switches ("Ada") use ("-gnath");
3700 for Switches ("Ada") use ("-gnatP");
3709 @c ---------------------------------------------
3710 @node Tools Supporting Project Files
3711 @chapter Tools Supporting Project Files
3712 @c ---------------------------------------------
3717 * gnatmake and Project Files::
3718 * The GNAT Driver and Project Files::
3719 * The Development Environments::
3722 @c ---------------------------------------------
3723 @node gnatmake and Project Files
3724 @section gnatmake and Project Files
3725 @c ---------------------------------------------
3728 This section covers several topics related to @command{gnatmake} and
3729 project files: defining ^switches^switches^ for @command{gnatmake}
3730 and for the tools that it invokes; specifying configuration pragmas;
3731 the use of the @code{Main} attribute; building and rebuilding library project
3735 * Switches Related to Project Files::
3736 * Switches and Project Files::
3737 * Specifying Configuration Pragmas::
3738 * Project Files and Main Subprograms::
3739 * Library Project Files::
3742 @c ---------------------------------------------
3743 @node Switches Related to Project Files
3744 @subsection Switches Related to Project Files
3745 @c ---------------------------------------------
3748 The following switches are used by GNAT tools that support project files:
3752 @item ^-P^/PROJECT_FILE=^@var{project}
3753 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
3754 Indicates the name of a project file. This project file will be parsed with
3755 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
3756 if any, and using the external references indicated
3757 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
3759 There may zero, one or more spaces between @option{-P} and @var{project}.
3762 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3764 Since the Project Manager parses the project file only after all the switches
3765 on the command line are checked, the order of the switches
3766 @option{^-P^/PROJECT_FILE^},
3767 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3768 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3770 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3771 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3772 Indicates that external variable @var{name} has the value @var{value}.
3773 The Project Manager will use this value for occurrences of
3774 @code{external(name)} when parsing the project file.
3777 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3785 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3786 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3787 @var{name}, only the last one is used.
3789 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3790 takes precedence over the value of the same name in the environment.
3792 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3793 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3794 Indicates the verbosity of the parsing of GNAT project files.
3797 @option{-vP0} means Default;
3798 @option{-vP1} means Medium;
3799 @option{-vP2} means High.
3803 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3807 The default is ^Default^DEFAULT^: no output for syntactically correct
3809 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3810 only the last one is used.
3812 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3813 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3814 Add directory <dir> at the beginning of the project search path, in order,
3815 after the current working directory.
3819 @cindex @option{-eL} (any project-aware tool)
3820 Follow all symbolic links when processing project files.
3823 @item ^--subdirs^/SUBDIRS^=<subdir>
3824 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3825 This switch is recognized by gnatmake and gnatclean. It indicate that the real
3826 directories (except the source directories) are the subdirectories <subdir>
3827 of the directories specified in the project files. This applies in particular
3828 to object directories, library directories and exec directories. If the
3829 subdirectories do not exist, they are created automatically.
3833 @c ---------------------------------------------
3834 @node Switches and Project Files
3835 @subsection Switches and Project Files
3836 @c ---------------------------------------------
3840 It is not currently possible to specify VMS style qualifiers in the project
3841 files; only Unix style ^switches^switches^ may be specified.
3844 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3845 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3846 attribute, a @code{Switches} attribute, or both;
3847 as their names imply, these ^switch^switch^-related
3848 attributes affect the ^switches^switches^ that are used for each of these GNAT
3850 @command{gnatmake} is invoked. As will be explained below, these
3851 component-specific ^switches^switches^ precede
3852 the ^switches^switches^ provided on the @command{gnatmake} command line.
3854 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3855 indexed by language name (case insensitive) whose value is a string list.
3858 @smallexample @c projectfile
3861 for ^Default_Switches^Default_Switches^ ("Ada")
3862 use ("^-gnaty^-gnaty^",
3869 The @code{Switches} attribute is indexed on a file name (which may or may
3870 not be case sensitive, depending
3871 on the operating system) whose value is a string list. For example:
3873 @smallexample @c projectfile
3876 for Switches ("main1.adb")
3878 for Switches ("main2.adb")
3885 For the @code{Builder} package, the file names must designate source files
3886 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
3887 file names must designate @file{ALI} or source files for main subprograms.
3888 In each case just the file name without an explicit extension is acceptable.
3890 For each tool used in a program build (@command{gnatmake}, the compiler, the
3891 binder, and the linker), the corresponding package @dfn{contributes} a set of
3892 ^switches^switches^ for each file on which the tool is invoked, based on the
3893 ^switch^switch^-related attributes defined in the package.
3894 In particular, the ^switches^switches^
3895 that each of these packages contributes for a given file @var{f} comprise:
3898 @item the value of attribute @code{Switches (@var{f})},
3899 if it is specified in the package for the given file,
3900 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
3901 if it is specified in the package.
3906 If neither of these attributes is defined in the package, then the package does
3907 not contribute any ^switches^switches^ for the given file.
3909 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
3910 two sets, in the following order: those contributed for the file
3911 by the @code{Builder} package;
3912 and the switches passed on the command line.
3914 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
3915 the ^switches^switches^ passed to the tool comprise three sets,
3916 in the following order:
3920 the applicable ^switches^switches^ contributed for the file
3921 by the @code{Builder} package in the project file supplied on the command line;
3924 those contributed for the file by the package (in the relevant project file --
3925 see below) corresponding to the tool; and
3928 the applicable switches passed on the command line.
3931 The term @emph{applicable ^switches^switches^} reflects the fact that
3932 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
3933 tools, depending on the individual ^switch^switch^.
3935 @command{gnatmake} may invoke the compiler on source files from different
3936 projects. The Project Manager will use the appropriate project file to
3937 determine the @code{Compiler} package for each source file being compiled.
3938 Likewise for the @code{Binder} and @code{Linker} packages.
3940 As an example, consider the following package in a project file:
3942 @smallexample @c projectfile
3946 for ^Default_Switches^Default_Switches^ ("Ada")
3948 for Switches ("a.adb")
3950 for Switches ("b.adb")
3959 If @command{gnatmake} is invoked with this project file, and it needs to
3960 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
3961 @file{a.adb} will be compiled with the ^switch^switch^
3963 @file{b.adb} with ^switches^switches^
3965 and @option{^-gnaty^-gnaty^},
3966 and @file{c.adb} with @option{^-g^-g^}.
3968 The following example illustrates the ordering of the ^switches^switches^
3969 contributed by different packages:
3971 @smallexample @c projectfile
3975 for Switches ("main.adb")
3984 for Switches ("main.adb")
3992 If you issue the command:
3995 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
3999 then the compiler will be invoked on @file{main.adb} with the following
4000 sequence of ^switches^switches^
4003 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
4007 with the last @option{^-O^-O^}
4008 ^switch^switch^ having precedence over the earlier ones;
4009 several other ^switches^switches^
4010 (such as @option{^-c^-c^}) are added implicitly.
4012 The ^switches^switches^
4014 and @option{^-O1^-O1^} are contributed by package
4015 @code{Builder}, @option{^-O2^-O2^} is contributed
4016 by the package @code{Compiler}
4017 and @option{^-O0^-O0^} comes from the command line.
4019 The @option{^-g^-g^}
4020 ^switch^switch^ will also be passed in the invocation of
4023 A final example illustrates switch contributions from packages in different
4026 @smallexample @c projectfile
4029 for Source_Files use ("pack.ads", "pack.adb");
4031 for ^Default_Switches^Default_Switches^ ("Ada")
4032 use ("^-gnata^-gnata^");
4040 for Source_Files use ("foo_main.adb", "bar_main.adb");
4042 for Switches ("foo_main.adb")
4052 procedure Foo_Main is
4061 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
4065 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
4066 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
4067 @option{^-gnato^-gnato^} (passed on the command line).
4068 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
4069 are @option{^-g^-g^} from @code{Proj4.Builder},
4070 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
4071 and @option{^-gnato^-gnato^} from the command line.
4073 When using @command{gnatmake} with project files, some ^switches^switches^ or
4074 arguments may be expressed as relative paths. As the working directory where
4075 compilation occurs may change, these relative paths are converted to absolute
4076 paths. For the ^switches^switches^ found in a project file, the relative paths
4077 are relative to the project file directory, for the switches on the command
4078 line, they are relative to the directory where @command{gnatmake} is invoked.
4079 The ^switches^switches^ for which this occurs are:
4085 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
4087 ^-o^-o^, object files specified in package @code{Linker} or after
4088 -largs on the command line). The exception to this rule is the ^switch^switch^
4089 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
4091 @c ---------------------------------------------
4092 @node Specifying Configuration Pragmas
4093 @subsection Specifying Configuration Pragmas
4094 @c ---------------------------------------------
4097 When using @command{gnatmake} with project files, if there exists a file
4098 @file{gnat.adc} that contains configuration pragmas, this file will be
4101 Configuration pragmas can be defined by means of the following attributes in
4102 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
4103 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
4105 Both these attributes are single string attributes. Their values is the path
4106 name of a file containing configuration pragmas. If a path name is relative,
4107 then it is relative to the project directory of the project file where the
4108 attribute is defined.
4110 When compiling a source, the configuration pragmas used are, in order,
4111 those listed in the file designated by attribute
4112 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
4113 project file, if it is specified, and those listed in the file designated by
4114 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
4115 the project file of the source, if it exists.
4117 @c ---------------------------------------------
4118 @node Project Files and Main Subprograms
4119 @subsection Project Files and Main Subprograms
4120 @c ---------------------------------------------
4123 When using a project file, you can invoke @command{gnatmake}
4124 with one or several main subprograms, by specifying their source files on the
4128 gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb
4132 Each of these needs to be a source file of the same project, except
4133 when the switch ^-u^/UNIQUE^ is used.
4135 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
4136 same project, one of the project in the tree rooted at the project specified
4137 on the command line. The package @code{Builder} of this common project, the
4138 "main project" is the one that is considered by @command{gnatmake}.
4140 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
4141 imported directly or indirectly by the project specified on the command line.
4142 Note that if such a source file is not part of the project specified on the
4143 command line, the ^switches^switches^ found in package @code{Builder} of the
4144 project specified on the command line, if any, that are transmitted
4145 to the compiler will still be used, not those found in the project file of
4148 When using a project file, you can also invoke @command{gnatmake} without
4149 explicitly specifying any main, and the effect depends on whether you have
4150 defined the @code{Main} attribute. This attribute has a string list value,
4151 where each element in the list is the name of a source file (the file
4152 extension is optional) that contains a unit that can be a main subprogram.
4154 If the @code{Main} attribute is defined in a project file as a non-empty
4155 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
4156 line, then invoking @command{gnatmake} with this project file but without any
4157 main on the command line is equivalent to invoking @command{gnatmake} with all
4158 the file names in the @code{Main} attribute on the command line.
4161 @smallexample @c projectfile
4164 for Main use ("main1.adb", "main2.adb", "main3.adb");
4170 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
4172 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}.
4174 When the project attribute @code{Main} is not specified, or is specified
4175 as an empty string list, or when the switch @option{-u} is used on the command
4176 line, then invoking @command{gnatmake} with no main on the command line will
4177 result in all immediate sources of the project file being checked, and
4178 potentially recompiled. Depending on the presence of the switch @option{-u},
4179 sources from other project files on which the immediate sources of the main
4180 project file depend are also checked and potentially recompiled. In other
4181 words, the @option{-u} switch is applied to all of the immediate sources of the
4184 When no main is specified on the command line and attribute @code{Main} exists
4185 and includes several mains, or when several mains are specified on the
4186 command line, the default ^switches^switches^ in package @code{Builder} will
4187 be used for all mains, even if there are specific ^switches^switches^
4188 specified for one or several mains.
4190 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
4191 the specific ^switches^switches^ for each main, if they are specified.
4193 @c ---------------------------------------------
4194 @node Library Project Files
4195 @subsection Library Project Files
4196 @c ---------------------------------------------
4199 When @command{gnatmake} is invoked with a main project file that is a library
4200 project file, it is not allowed to specify one or more mains on the command
4203 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
4204 ^-l^/ACTION=LINK^ have special meanings.
4207 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
4208 to @command{gnatmake} that @command{gnatbind} should be invoked for the
4211 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
4212 to @command{gnatmake} that the binder generated file should be compiled
4213 (in the case of a stand-alone library) and that the library should be built.
4216 @c ---------------------------------------------
4217 @node The GNAT Driver and Project Files
4218 @section The GNAT Driver and Project Files
4219 @c ---------------------------------------------
4222 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
4223 can benefit from project files:
4224 (@command{^gnatbind^gnatbind^},
4225 @command{^gnatcheck^gnatcheck^},
4226 @command{^gnatclean^gnatclean^},
4227 @command{^gnatelim^gnatelim^},
4228 @command{^gnatfind^gnatfind^},
4229 @command{^gnatlink^gnatlink^},
4230 @command{^gnatls^gnatls^},
4231 @command{^gnatmetric^gnatmetric^},
4232 @command{^gnatpp^gnatpp^},
4233 @command{^gnatstub^gnatstub^},
4234 and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
4235 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
4236 They must be invoked through the @command{gnat} driver.
4238 The @command{gnat} driver is a wrapper that accepts a number of commands and
4239 calls the corresponding tool. It was designed initially for VMS platforms (to
4240 convert VMS qualifiers to Unix-style switches), but it is now available on all
4243 On non-VMS platforms, the @command{gnat} driver accepts the following commands
4247 @item BIND to invoke @command{^gnatbind^gnatbind^}
4248 @item CHOP to invoke @command{^gnatchop^gnatchop^}
4249 @item CLEAN to invoke @command{^gnatclean^gnatclean^}
4250 @item COMP or COMPILE to invoke the compiler
4251 @item ELIM to invoke @command{^gnatelim^gnatelim^}
4252 @item FIND to invoke @command{^gnatfind^gnatfind^}
4253 @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
4254 @item LINK to invoke @command{^gnatlink^gnatlink^}
4255 @item LS or LIST to invoke @command{^gnatls^gnatls^}
4256 @item MAKE to invoke @command{^gnatmake^gnatmake^}
4257 @item NAME to invoke @command{^gnatname^gnatname^}
4258 @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
4259 @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
4260 @item METRIC to invoke @command{^gnatmetric^gnatmetric^}
4261 @item STUB to invoke @command{^gnatstub^gnatstub^}
4262 @item XREF to invoke @command{^gnatxref^gnatxref^}
4267 (note that the compiler is invoked using the command
4268 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
4270 On non-VMS platforms, between @command{gnat} and the command, two
4271 special switches may be used:
4274 @item @command{-v} to display the invocation of the tool.
4275 @item @command{-dn} to prevent the @command{gnat} driver from removing
4276 the temporary files it has created. These temporary files are
4277 configuration files and temporary file list files.
4282 The command may be followed by switches and arguments for the invoked
4286 gnat bind -C main.ali
4292 Switches may also be put in text files, one switch per line, and the text
4293 files may be specified with their path name preceded by '@@'.
4296 gnat bind @@args.txt main.ali
4300 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
4301 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
4302 (@option{^-P^/PROJECT_FILE^},
4303 @option{^-X^/EXTERNAL_REFERENCE^} and
4304 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
4305 the switches of the invoking tool.
4307 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
4308 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
4309 the immediate sources of the specified project file.
4311 When GNAT METRIC is used with a project file, but with no source
4312 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
4313 with all the immediate sources of the specified project file and with
4314 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
4317 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
4318 a project file, no source is specified on the command line and
4319 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
4320 the underlying tool (^gnatpp^gnatpp^ or
4321 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
4322 not only for the immediate sources of the main project.
4324 (-U stands for Universal or Union of the project files of the project tree)
4327 For each of the following commands, there is optionally a corresponding
4328 package in the main project.
4331 @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
4333 @item package @code{Check} for command CHECK (invoking
4334 @code{^gnatcheck^gnatcheck^})
4336 @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
4338 @item package @code{Cross_Reference} for command XREF (invoking
4339 @code{^gnatxref^gnatxref^})
4341 @item package @code{Eliminate} for command ELIM (invoking
4342 @code{^gnatelim^gnatelim^})
4344 @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
4346 @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
4348 @item package @code{Gnatstub} for command STUB
4349 (invoking @code{^gnatstub^gnatstub^})
4351 @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
4353 @item package @code{Check} for command CHECK
4354 (invoking @code{^gnatcheck^gnatcheck^})
4356 @item package @code{Metrics} for command METRIC
4357 (invoking @code{^gnatmetric^gnatmetric^})
4359 @item package @code{Pretty_Printer} for command PP or PRETTY
4360 (invoking @code{^gnatpp^gnatpp^})
4365 Package @code{Gnatls} has a unique attribute @code{Switches},
4366 a simple variable with a string list value. It contains ^switches^switches^
4367 for the invocation of @code{^gnatls^gnatls^}.
4369 @smallexample @c projectfile
4382 All other packages have two attribute @code{Switches} and
4383 @code{^Default_Switches^Default_Switches^}.
4385 @code{Switches} is an indexed attribute, indexed by the
4386 source file name, that has a string list value: the ^switches^switches^ to be
4387 used when the tool corresponding to the package is invoked for the specific
4390 @code{^Default_Switches^Default_Switches^} is an attribute,
4391 indexed by the programming language that has a string list value.
4392 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
4393 ^switches^switches^ for the invocation of the tool corresponding
4394 to the package, except if a specific @code{Switches} attribute
4395 is specified for the source file.
4397 @smallexample @c projectfile
4401 for Source_Dirs use ("**");
4412 for ^Default_Switches^Default_Switches^ ("Ada")
4413 use ("^-gnatv^-gnatv^",
4414 "^-gnatwa^-gnatwa^");
4420 for ^Default_Switches^Default_Switches^ ("Ada")
4428 for ^Default_Switches^Default_Switches^ ("Ada")
4430 for Switches ("main.adb")
4439 for ^Default_Switches^Default_Switches^ ("Ada")
4446 package Cross_Reference is
4447 for ^Default_Switches^Default_Switches^ ("Ada")
4452 end Cross_Reference;
4458 With the above project file, commands such as
4461 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
4462 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
4463 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
4464 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
4465 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
4469 will set up the environment properly and invoke the tool with the switches
4470 found in the package corresponding to the tool:
4471 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
4472 except @code{Switches ("main.adb")}
4473 for @code{^gnatlink^gnatlink^}.
4474 It is also possible to invoke some of the tools,
4475 (@code{^gnatcheck^gnatcheck^},
4476 @code{^gnatmetric^gnatmetric^},
4477 and @code{^gnatpp^gnatpp^})
4478 on a set of project units thanks to the combination of the switches
4479 @option{-P}, @option{-U} and possibly the main unit when one is interested
4480 in its closure. For instance,
4486 will compute the metrics for all the immediate units of project
4489 gnat metric -Pproj -U
4493 will compute the metrics for all the units of the closure of projects
4494 rooted at @code{proj}.
4496 gnat metric -Pproj -U main_unit
4500 will compute the metrics for the closure of units rooted at
4501 @code{main_unit}. This last possibility relies implicitly
4502 on @command{gnatbind}'s option @option{-R}. But if the argument files for the
4503 tool invoked by the @command{gnat} driver are explicitly specified
4504 either directly or through the tool @option{-files} option, then the tool
4505 is called only for these explicitly specified files.
4507 @c ---------------------------------------------
4508 @node The Development Environments
4509 @section The Development Environments
4510 @c ---------------------------------------------
4513 See the appropriate manuals for more details. These environments will
4514 store a number of settings in the project itself, when they are meant
4515 to be shared by the whole team working on the project. Here are the
4516 attributes defined in the package @b{IDE} in projects.
4520 This is a simple attribute. Its value is a string that designates the remote
4521 host in a cross-compilation environment, to be used for remote compilation and
4522 debugging. This field should not be specified when running on the local
4526 This is a simple attribute. Its value is a string that specifies the
4527 name of IP address of the embedded target in a cross-compilation environment,
4528 on which the program should execute.
4530 @item Communication_Protocol
4531 This is a simple string attribute. Its value is the name of the protocol
4532 to use to communicate with the target in a cross-compilation environment,
4533 e.g.@: @code{"wtx"} or @code{"vxworks"}.
4535 @item Compiler_Command
4536 This is an associative array attribute, whose domain is a language name. Its
4537 value is string that denotes the command to be used to invoke the compiler.
4538 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
4539 gnatmake, in particular in the handling of switches.
4541 @item Debugger_Command
4542 This is simple attribute, Its value is a string that specifies the name of
4543 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
4545 @item Default_Switches
4546 This is an associative array attribute. Its indexes are the name of the
4547 external tools that the GNAT Programming System (GPS) is supporting. Its
4548 value is a list of switches to use when invoking that tool.
4551 This is a simple attribute. Its value is a string that specifies the name
4552 of the @command{gnatls} utility to be used to retrieve information about the
4553 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
4556 This is a simple attribute. Its value is a string used to specify the
4557 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
4558 ClearCase or Perforce.
4561 This is a simple attribute. Its value is a string that specifies the name
4562 of the @command{gnat} utility to be used when executing various tools from
4563 GPS, in particular @code{"gnat pp"}, @code{"gnat stub"},@dots{}
4565 @item VCS_File_Check
4566 This is a simple attribute. Its value is a string that specifies the
4567 command used by the VCS to check the validity of a file, either
4568 when the user explicitly asks for a check, or as a sanity check before
4572 This is a simple attribute. Its value is a string that specifies
4573 the command used by the VCS to check the validity of a log file.
4575 @item VCS_Repository_Root
4576 The VCS repository root path. This is used to create tags or branches
4577 of the repository. For subversion the value should be the @code{URL}
4578 as specified to check-out the working copy of the repository.
4580 @item VCS_Patch_Root
4581 The local root directory to use for building patch file. All patch chunks
4582 will be relative to this path. The root project directory is used if
4583 this value is not defined.