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 used in the string list @code{Source_Dirs}, it is an error
407 to have several files with the same source file name in the same directory
408 @code{"**"} subtree, since there would be an ambiguity as to which one should
409 be used. However, two files with the same source file name may exist in two
410 single directories or directory subtrees. In this case, the one in the first
411 directory or directory subtree is a source of the project.
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, usually @b{Library_Interface}, in addition
1761 to the two attributes that make a project a Library Project
1762 (@code{Library_Name} and @code{Library_Dir}). This third attribute may also be
1763 @b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada
1764 and takes a list of units as parameter. @b{Interfaces} works for any supported
1765 language and takes a list of sources as parameter.
1768 @item @b{Library_Interface}:
1769 @cindex @code{Library_Interface}
1770 This attribute defines an explicit subset of the units of the project. Units
1771 from projects importing this library project may only "with" units whose
1772 sources are listed in the @code{Library_Interface}. Other sources are
1773 considered implementation units.
1775 @smallexample @c projectfile
1777 for Library_Dir use "lib";
1778 for Library_Name use "loggin";
1779 for Library_Interface use ("lib1", "lib2"); -- unit names
1783 @item @b{Interfaces}
1784 This attribute defines an explicit subset of the source files of a project.
1785 Sources from projects importing this project, can only depend on sources from
1786 this subset. This attribute can be used on non library projects. It can also
1787 be used as a replacement for attribute @code{Library_Interface}, in which
1788 case, units have to be replaced by source files. For multi-language library
1789 projects, it is the only way to make the project a Stand-Alone Library project
1790 whose interface is not purely Ada.
1792 @item @b{Library_Standalone}:
1793 @cindex @code{Library_Standalone}
1794 This attribute defines the kind of standalone library to
1795 build. Values are either @code{standard} (the default), @code{no} or
1796 @code{encapsulated}. When @code{standard} is used the code to elaborate and
1797 finalize the library is embedded, when @code{encapsulated} is used the
1798 library can furthermore only depends on static libraries (including
1799 the GNAT runtime). This attribute can be set to @code{no} to make it clear
1800 that the library should not be standalone in which case the
1801 @code{Library_Interface} should not defined.
1803 @smallexample @c projectfile
1805 for Library_Dir use "lib";
1806 for Library_Name use "loggin";
1807 for Library_Interface use ("lib1", "lib2"); -- unit names
1808 for Library_Standalone use "encapsulated";
1814 In order to include the elaboration code in the stand-alone library, the binder
1815 is invoked on the closure of the library units creating a package whose name
1816 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1817 This binder-generated package includes @b{initialization} and @b{finalization}
1818 procedures whose names depend on the library name (@code{logginginit} and
1819 @code{loggingfinal} in the example). The object corresponding to this package is
1820 included in the library.
1823 @item @b{Library_Auto_Init}:
1824 @cindex @code{Library_Auto_Init}
1825 A dynamic stand-alone Library is automatically initialized
1826 if automatic initialization of Stand-alone Libraries is supported on the
1827 platform and if attribute @b{Library_Auto_Init} is not specified or
1828 is specified with the value "true". A static Stand-alone Library is never
1829 automatically initialized. Specifying "false" for this attribute
1830 prevent automatic initialization.
1832 When a non-automatically initialized stand-alone library is used in an
1833 executable, its initialization procedure must be called before any service of
1834 the library is used. When the main subprogram is in Ada, it may mean that the
1835 initialization procedure has to be called during elaboration of another
1838 @item @b{Library_Dir}:
1839 @cindex @code{Library_Dir}
1840 For a stand-alone library, only the @file{ALI} files of the interface units
1841 (those that are listed in attribute @code{Library_Interface}) are copied to
1842 the library directory. As a consequence, only the interface units may be
1843 imported from Ada units outside of the library. If other units are imported,
1844 the binding phase will fail.
1846 @item @b{Binder.Default_Switches}:
1847 When a stand-alone library is bound, the switches that are specified in
1848 the attribute @b{Binder.Default_Switches ("Ada")} are
1849 used in the call to @command{gnatbind}.
1851 @item @b{Library_Src_Dir}:
1852 @cindex @code{Library_Src_Dir}
1853 This attribute defines the location (absolute or relative to the project
1854 directory) where the sources of the interface units are copied at
1856 These sources includes the specs of the interface units along with the closure
1857 of sources necessary to compile them successfully. That may include bodies and
1858 subunits, when pragmas @code{Inline} are used, or when there is a generic
1859 units in the spec. This directory cannot point to the object directory or
1860 one of the source directories, but it can point to the library directory,
1861 which is the default value for this attribute.
1863 @item @b{Library_Symbol_Policy}:
1864 @cindex @code{Library_Symbol_Policy}
1865 This attribute controls the export of symbols and, on some platforms (like
1866 VMS) that have the notions of major and minor IDs built in the library
1867 files, it controls the setting of these IDs. It is not supported on all
1868 platforms (where it will just have no effect). It may have one of the
1872 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1873 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1874 is not defined, then it is equivalent to policy "autonomous". If there
1875 are exported symbols in the reference symbol file that are not in the
1876 object files of the interfaces, the major ID of the library is increased.
1877 If there are symbols in the object files of the interfaces that are not
1878 in the reference symbol file, these symbols are put at the end of the list
1879 in the newly created symbol file and the minor ID is increased.
1880 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1881 defined. The library will fail to build if the exported symbols in the
1882 object files of the interfaces do not match exactly the symbol in the
1884 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1885 The library will fail to build if there are symbols in the symbol file that
1886 are not in the exported symbols of the object files of the interfaces.
1887 Additional symbols in the object files are not added to the symbol file.
1888 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1889 must designate an existing file in the object directory. This symbol file
1890 is passed directly to the underlying linker without any symbol processing.
1894 @item @b{Library_Reference_Symbol_File}
1895 @cindex @code{Library_Reference_Symbol_File}
1896 This attribute may define the path name of a reference symbol file that is
1897 read when the symbol policy is either "compliant" or "controlled", on
1898 platforms that support symbol control, such as VMS, when building a
1899 stand-alone library. The path may be an absolute path or a path relative
1900 to the project directory.
1902 @item @b{Library_Symbol_File}
1903 @cindex @code{Library_Symbol_File}
1904 This attribute may define the name of the symbol file to be created when
1905 building a stand-alone library when the symbol policy is either "compliant",
1906 "controlled" or "restricted", on platforms that support symbol control,
1907 such as VMS. When symbol policy is "direct", then a file with this name
1908 must exist in the object directory.
1911 @c ---------------------------------------------
1912 @node Installing a library with project files
1913 @subsection Installing a library with project files
1914 @c ---------------------------------------------
1917 When using project files, library installation is part of the library build
1918 process. Thus no further action is needed in order to make use of the
1919 libraries that are built as part of the general application build. A usable
1920 version of the library is installed in the directory specified by the
1921 @code{Library_Dir} attribute of the library project file.
1923 You may want to install a library in a context different from where the library
1924 is built. This situation arises with third party suppliers, who may want
1925 to distribute a library in binary form where the user is not expected to be
1926 able to recompile the library. The simplest option in this case is to provide
1927 a project file slightly different from the one used to build the library, by
1928 using the @code{externally_built} attribute. @ref{Using Library Projects}
1930 @c ---------------------------------------------
1931 @node Project Extension
1932 @section Project Extension
1933 @c ---------------------------------------------
1936 During development of a large system, it is sometimes necessary to use
1937 modified versions of some of the source files, without changing the original
1938 sources. This can be achieved through the @b{project extension} facility.
1940 Suppose for instance that our example @code{Build} project is build every night
1941 for the whole team, in some shared directory. A developer usually need to work
1942 on a small part of the system, and might not want to have a copy of all the
1943 sources and all the object files (mostly because that would require too much
1944 disk space, time to recompile everything). He prefers to be able to override
1945 some of the source files in his directory, while taking advantage of all the
1946 object files generated at night.
1948 Another example can be taken from large software systems, where it is common to have
1949 multiple implementations of a common interface; in Ada terms, multiple
1950 versions of a package body for the same spec. For example, one implementation
1951 might be safe for use in tasking programs, while another might only be used
1952 in sequential applications. This can be modeled in GNAT using the concept
1953 of @emph{project extension}. If one project (the ``child'') @emph{extends}
1954 another project (the ``parent'') then by default all source files of the
1955 parent project are inherited by the child, but the child project can
1956 override any of the parent's source files with new versions, and can also
1957 add new files or remove unnecessary ones.
1958 This facility is the project analog of a type extension in
1959 object-oriented programming. Project hierarchies are permitted (an extending
1960 project may itself be extended), and a project that
1961 extends a project can also import other projects.
1963 A third example is that of using project extensions to provide different
1964 versions of the same system. For instance, assume that a @code{Common}
1965 project is used by two development branches. One of the branches has now
1966 been frozen, and no further change can be done to it or to @code{Common}.
1967 However, the other development branch still needs evolution of @code{Common}.
1968 Project extensions provide a flexible solution to create a new version
1969 of a subsystem while sharing and reusing as much as possible from the original
1972 A project extension inherits implicitly all the sources and objects from the
1973 project it extends. It is possible to create a new version of some of the
1974 sources in one of the additional source dirs of the extending project. Those new
1975 versions hide the original versions. Adding new sources or removing existing
1976 ones is also possible. Here is an example on how to extend the project
1977 @code{Build} from previous examples:
1979 @smallexample @c projectfile
1980 project Work extends "../bld/build.gpr" is
1985 The project after @b{extends} is the one being extended. As usual, it can be
1986 specified using an absolute path, or a path relative to any of the directories
1987 in the project path (@pxref{Project Dependencies}). This project does not
1988 specify source or object directories, so the default value for these attribute
1989 will be used that is to say the current directory (where project @code{Work} is
1990 placed). We can already compile that project with
1997 If no sources have been placed in the current directory, this command
1998 won't do anything, since this project does not change the
1999 sources it inherited from @code{Build}, therefore all the object files
2000 in @code{Build} and its dependencies are still valid and are reused
2003 Suppose we now want to supply an alternate version of @file{pack.adb}
2004 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
2005 We can create the new file Work's current directory (likely
2006 by copying the one from the @code{Build} project and making changes to
2007 it. If new packages are needed at the same time, we simply create
2008 new files in the source directory of the extending project.
2010 When we recompile, @command{gnatmake} will now automatically recompile
2011 this file (thus creating @file{pack.o} in the current directory) and
2012 any file that depends on it (thus creating @file{proc.o}). Finally, the
2013 executable is also linked locally.
2015 Note that we could have obtained the desired behavior using project import
2016 rather than project inheritance. A @code{base} project would contain the
2017 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
2018 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
2019 cannot contain the original version of @file{pack.adb} otherwise there would be
2020 2 versions of the same unit in the closure of the project and this is not
2021 allowed. Generally speaking, it is not recommended to put the spec and the
2022 body of a unit in different projects since this affects their autonomy and
2025 In a project file that extends another project, it is possible to
2026 indicate that an inherited source is @b{not part} of the sources of the
2027 extending project. This is necessary sometimes when a package spec has
2028 been overridden and no longer requires a body: in this case, it is
2029 necessary to indicate that the inherited body is not part of the sources
2030 of the project, otherwise there will be a compilation error
2031 when compiling the spec.
2033 @cindex @code{Excluded_Source_Files}
2034 @cindex @code{Excluded_Source_List_File}
2035 For that purpose, the attribute @b{Excluded_Source_Files} is used.
2036 Its value is a list of file names.
2037 It is also possible to use attribute @code{Excluded_Source_List_File}.
2038 Its value is the path of a text file containing one file name per
2041 @smallexample @c @projectfile
2042 project Work extends "../bld/build.gpr" is
2043 for Source_Files use ("pack.ads");
2044 -- New spec of Pkg does not need a completion
2045 for Excluded_Source_Files use ("pack.adb");
2050 All packages that are not declared in the extending project are inherited from
2051 the project being extended, with their attributes, with the exception of
2052 @code{Linker'Linker_Options} which is never inherited. In particular, an
2053 extending project retains all the switches specified in the project being
2056 At the project level, if they are not declared in the extending project, some
2057 attributes are inherited from the project being extended. They are:
2058 @code{Languages}, @code{Main} (for a root non library project) and
2059 @code{Library_Name} (for a project extending a library project)
2062 * Project Hierarchy Extension::
2065 @c ---------------------------------------------
2066 @node Project Hierarchy Extension
2067 @subsection Project Hierarchy Extension
2068 @c ---------------------------------------------
2071 One of the fundamental restrictions in project extension is the following:
2072 @b{A project is not allowed to import directly or indirectly at the same time an
2073 extending project and one of its ancestors}.
2075 By means of example, consider the following hierarchy of projects.
2078 a.gpr contains package A1
2079 b.gpr, imports a.gpr and contains B1, which depends on A1
2080 c.gpr, imports b.gpr and contains C1, which depends on B1
2084 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2085 create several extending projects:
2088 a_ext.gpr which extends a.gpr, and overrides A1
2089 b_ext.gpr which extends b.gpr and imports a_ext.gpr
2090 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2094 @smallexample @c projectfile
2095 project A_Ext extends "a.gpr" is
2096 for Source_Files use ("a1.adb", "a1.ads");
2100 project B_Ext extends "b.gpr" is
2104 project C_Ext extends "c.gpr" is
2105 for Source_Files use ("c1.adb");
2110 The extension @file{b_ext.gpr} is required, even though we are not overriding
2111 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2112 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2115 When extending a large system spanning multiple projects, it is often
2116 inconvenient to extend every project in the hierarchy that is impacted by a
2117 small change introduced in a low layer. In such cases, it is possible to create
2118 an @b{implicit extension} of entire hierarchy using @b{extends all}
2121 When the project is extended using @code{extends all} inheritance, all projects
2122 that are imported by it, both directly and indirectly, are considered virtually
2123 extended. That is, the project manager creates implicit projects
2124 that extend every project in the hierarchy; all these implicit projects do not
2125 control sources on their own and use the object directory of
2126 the "extending all" project.
2128 It is possible to explicitly extend one or more projects in the hierarchy
2129 in order to modify the sources. These extending projects must be imported by
2130 the "extending all" project, which will replace the corresponding virtual
2131 projects with the explicit ones.
2133 When building such a project hierarchy extension, the project manager will
2134 ensure that both modified sources and sources in implicit extending projects
2135 that depend on them, are recompiled.
2137 Thus, in our example we could create the following projects instead:
2140 a_ext.gpr, extends a.gpr and overrides A1
2141 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2146 @smallexample @c projectfile
2147 project A_Ext extends "a.gpr" is
2148 for Source_Files use ("a1.adb", "a1.ads");
2152 project C_Ext extends all "c.gpr" is
2153 for Source_Files use ("c1.adb");
2158 When building project @file{c_ext.gpr}, the entire modified project space is
2159 considered for recompilation, including the sources of @file{b.gpr} that are
2160 impacted by the changes in @code{A1} and @code{C1}.
2162 @c ---------------------------------------------
2163 @node Aggregate Projects
2164 @section Aggregate Projects
2165 @c ---------------------------------------------
2169 Aggregate projects are an extension of the project paradigm, and are
2170 meant to solve a few specific use cases that cannot be solved directly
2171 using standard projects. This section will go over a few of these use
2172 cases to try and explain what you can use aggregate projects for.
2175 * Building all main programs from a single project tree::
2176 * Building a set of projects with a single command::
2177 * Define a build environment::
2178 * Performance improvements in builder::
2179 * Syntax of aggregate projects::
2180 * package Builder in aggregate projects::
2183 @c -----------------------------------------------------------
2184 @node Building all main programs from a single project tree
2185 @subsection Building all main programs from a single project tree
2186 @c -----------------------------------------------------------
2188 Most often, an application is organized into modules and submodules,
2189 which are very conveniently represented as a project tree or graph
2190 (the root project A @code{with}s the projects for each modules (say B and C),
2191 which in turn @code{with} projects for submodules.
2193 Very often, modules will build their own executables (for testing
2194 purposes for instance), or libraries (for easier reuse in various
2197 However, if you build your project through gnatmake or gprbuild, using
2204 this will only rebuild the main programs of project A, not those of the
2205 imported projects B and C. Therefore you have to spawn several
2206 gnatmake commands, one per project, to build all executables.
2207 This is a little inconvenient, but more importantly is inefficient
2208 (since gnatmake needs to do duplicate work to ensure that sources are
2209 up-to-date, and cannot easily compile things in parallel when using
2212 Also libraries are always rebuild when building a project.
2214 You could therefore define an aggregate project Agg that groups A, B
2215 and C. Then, when you build with
2221 this will build all mains from A, B and C.
2223 @smallexample @c projectfile
2224 aggregate project Agg is
2225 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2229 If B or C do not define any main program (through their Main
2230 attribute), all their sources are build. When you do not group them
2231 in the aggregate project, only those sources that are needed by A
2234 If you add a main to a project P not already explicitly referenced in the
2235 aggregate project, you will need to add "p.gpr" in the list of project
2236 files for the aggregate project, or the main will not be built when
2237 building the aggregate project.
2239 @c ---------------------------------------------------------
2240 @node Building a set of projects with a single command
2241 @subsection Building a set of projects with a single command
2242 @c ---------------------------------------------------------
2244 One other case is when you have multiple applications and libraries
2245 that are build independently from each other (but they can be build in
2246 parallel). For instance, you have a project tree rooted at A, and
2247 another one (which might share some subprojects) rooted at B.
2249 Using only gprbuild, you could do
2256 to build both. But again, gprbuild has to do some duplicate work for
2257 those files that are shared between the two, and cannot truly build
2258 things in parallel efficiently.
2260 If the two projects are really independent, share no sources other
2261 than through a common subproject, and have no source files with a
2262 common basename, you could create a project C that imports A and
2263 B. But these restrictions are often too strong, and one has to build
2264 them independently. An aggregate project does not have these
2265 limitations, and can aggregate two project trees that have common
2269 Aggregate projects can group projects with duplicate file names
2272 This scenario is particularly useful in environment like VxWork 653
2273 where the applications running in the multiple partitions can be build
2274 in parallel through a single gprbuild command. This also works nicely
2278 Aggregate projects can be used to build multiple partitions
2281 @c ---------------------------------------------
2282 @node Define a build environment
2283 @subsection Define a build environment
2284 @c ---------------------------------------------
2286 The environment variables at the time you launch gprbuild or gprbuild
2287 will influence the view these tools have of the project (PATH to find
2288 the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
2289 projects, environment variables that are referenced in project files
2290 through the "external" statement,...). Several command line switches
2291 can be used to override those (-X or -aP), but on some systems and
2292 with some projects, this might make the command line too long, and on
2293 all systems often make it hard to read.
2295 An aggregate project can be used to set the environment for all
2296 projects build through that aggregate. One of the nice aspects is that
2297 you can put the aggregate project under configuration management, and
2298 make sure all your user have a consistent environment when
2299 building. The syntax looks like
2301 @smallexample @c projectfile
2302 aggregate project Agg is
2303 for Project_Files use ("A.gpr", "B.gpr");
2304 for Project_Path use ("../dir1", "../dir1/dir2");
2305 for External ("BUILD") use "PRODUCTION";
2308 for Switches ("Ada") use ("-q");
2313 One of the often requested features in projects is to be able to
2314 reference external variables in @code{with} statements, as in
2316 @smallexample @c projectfile
2317 with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
2318 project MyProject is
2323 For various reasons, this isn't authorized. But using aggregate
2324 projects provide an elegant solution. For instance, you could
2325 use a project file like:
2327 @smallexample @c projectfile
2328 aggregate project Agg is
2329 for Project_Path use (external("SETUP") % "path");
2330 for Project_Files use ("myproject.gpr");
2333 with "prj.gpr"; -- searched on Agg'Project_Path
2334 project MyProject is
2339 @c --------------------------------------------
2340 @node Performance improvements in builder
2341 @subsection Performance improvements in builder
2342 @c --------------------------------------------
2344 The loading of aggregate projects is optimized in gprbuild and
2345 gnatmake, so that all files are searched for only once on the disk
2346 (thus reducing the number of system calls and contributing to faster
2347 compilation times especially on systems with sources on remote
2348 servers). As part of the loading, gprbuild and gnatmake compute how
2349 and where a source file should be compiled, and even if it is found
2350 several times in the aggregated projects it will be compiled only
2353 Since there is no ambiguity as to which switches should be used, files
2354 can be compiled in parallel (through the usual -j switch) and this can
2355 be done while maximizing the use of CPUs (compared to launching
2356 multiple gprbuild and gnatmake commands in parallel).
2358 @c -------------------------------------
2359 @node Syntax of aggregate projects
2360 @subsection Syntax of aggregate projects
2361 @c -------------------------------------
2363 An aggregate project follows the general syntax of project files. The
2364 recommended extension is still @file{.gpr}. However, a special
2365 @code{aggregate} qualifier must be put before the keyword
2368 An aggregate project cannot @code{with} any other project (standard or
2369 aggregate), except an abstract project which can be used to share
2370 attribute values. Building other aggregate projects from an aggregate
2371 project is done through the Project_Files attribute (see below).
2373 An aggregate project does not have any source files directly (only
2374 through other standard projects). Therefore a number of the standard
2375 attributes and packages are forbidden in an aggregate project. Here is the
2376 (non exhaustive) list:
2380 @item Source_Files, Source_List_File and other attributes dealing with
2382 @item Source_Dirs, Exec_Dir and Object_Dir
2383 @item Library_Dir, Library_Name and other library-related attributes
2386 @item Externally_Built
2387 @item Inherit_Source_Path
2388 @item Excluded_Source_Dirs
2389 @item Locally_Removed_Files
2390 @item Excluded_Source_Files
2391 @item Excluded_Source_List_File
2395 The only package that is authorized (albeit optional) is
2396 Builder. Other packages (in particular Compiler, Binder and Linker)
2397 are forbidden. It is an error to have any of these
2398 (and such an error prevents the proper loading of the aggregate
2401 Three new attributes have been created, which can only be used in the
2402 context of aggregate projects:
2405 @item @b{Project_Files}:
2406 @cindex @code{Project_Files}
2408 This attribute is compulsory (or else we are not aggregating any project,
2409 and thus not doing anything). It specifies a list of @file{.gpr} files
2410 that are grouped in the aggregate. The list may be empty. The project
2411 files can be either other aggregate projects, or standard projects. When
2412 grouping standard projects, you can have both the root of a project tree
2413 (and you do not need to specify all its imported projects), and any project
2416 Basically, the idea is to specify all those projects that have
2417 main programs you want to build and link, or libraries you want to
2418 build. You can even specify projects that do not use the Main
2419 attribute nor the @code{Library_*} attributes, and the result will be to
2420 build all their source files (not just the ones needed by other
2423 The file can include paths (absolute or relative). Paths are
2424 relative to the location of the aggregate project file itself (if
2425 you use a base name, we expect to find the .gpr file in the same
2426 directory as the aggregate project file). The extension @file{.gpr} is
2427 mandatory, since this attribute contains file names, not project names.
2429 Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
2430 latter indicates that any subdirectory (recursively) will be
2431 searched for matching files. The latter (@code{"**"}) can only occur at the
2432 last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
2433 not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
2434 to starting with @code{"./**"}.
2436 For now, the pattern @code{"*"} is only allowed in the filename part, not
2437 in the directory part. This is mostly for efficiency reasons to limit the
2438 number of system calls that are needed.
2440 Here are a few valid examples:
2442 @smallexample @c projectfile
2443 for Project_Files use ("a.gpr", "subdir/b.gpr");
2444 -- two specific projects relative to the directory of agg.gpr
2446 for Project_Files use ("**/*.gpr");
2447 -- all projects recursively
2450 @item @b{Project_Path}:
2451 @cindex @code{Project_Path}
2453 This attribute can be used to specify a list of directories in
2454 which to look for project files in @code{with} statements.
2456 When you specify a project in Project_Files
2457 say @code{"x/y/a.gpr"}), and this projects imports a project "b.gpr", only
2458 b.gpr is searched in the project path. a.gpr must be exactly at
2459 <dir of the aggregate>/x/y/a.gpr.
2461 This attribute, however, does not affect the search for the aggregated
2462 project files specified with @code{Project_Files}.
2464 Each aggregate project has its own (that is if agg1.gpr includes
2465 agg2.gpr, they can potentially both have a different project path).
2466 This project path is defined as the concatenation, in that order, of
2467 the current directory, followed by the command line -aP switches,
2468 then the directories from the Project_Path attribute, then the
2469 directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH env.
2470 variables, and finally the predefined directories.
2472 In the example above, agg2.gpr's project path is not influenced by
2473 the attribute agg1'Project_Path, nor is agg1 influenced by
2476 This can potentially lead to errors. In the following example:
2479 +---------------+ +----------------+
2480 | Agg1.gpr |-=--includes--=-->| Agg2.gpr |
2481 | 'project_path| | 'project_path |
2483 +---------------+ +----------------+
2488 +-------+ +---------+
2489 | P.gpr |<---------- withs --------| Q.gpr |
2490 +-------+---------\ +---------+
2495 +-------+ +---------+
2496 | R.gpr | | R'.gpr |
2497 +-------+ +---------+
2500 When looking for p.gpr, both aggregates find the same physical file on
2501 the disk. However, it might happen that with their different project
2502 paths, both aggregate projects would in fact find a different r.gpr.
2503 Since we have a common project (p.gpr) "with"ing two different r.gpr,
2504 this will be reported as an error by the builder.
2506 Directories are relative to the location of the aggregate project file.
2508 Here are a few valid examples:
2510 @smallexample @c projectfile
2511 for Project_Path use ("/usr/local/gpr", "gpr/");
2515 @cindex @code{External}
2517 This attribute can be used to set the value of environment
2518 variables as retrieved through the @code{external} statement
2519 in projects. It does not affect the environment variables
2520 themselves (so for instance you cannot use it to change the value
2521 of your PATH as seen from the spawned compiler).
2523 This attribute affects the external values as seen in the rest of
2524 the aggreate projects, and in the aggregated projects.
2526 The exact value of external a variable comes from one of three
2527 sources (each level overrides the previous levels):
2530 @item An External attribute in aggregate project, for instance
2531 @code{for External ("BUILD_MODE") use "DEBUG"};
2533 @item Environment variables
2535 These override the value given by the attribute, so that
2536 users can override the value set in the (presumably shared
2537 with others in his team) aggregate project.
2539 @item The -X command line switch to gprbuild and gnatmake
2541 This always takes precedence.
2545 This attribute is only taken into account in the main aggregate
2546 project (i.e. the one specified on the command line to gprbuild or
2547 natmake), and ignored in other aggregate projects. It is invalid
2548 in standard projects.
2549 The goal is to have a consistent value in all
2550 projects that are build through the aggregate, which would not
2551 be the case in the diamond case: A groups the aggregate
2552 projects B and C, which both (either directly or indirectly)
2553 build the project P. If B and C could set different values for
2554 the environment variables, we would have two different views of
2555 P, which in particular might impact the list of source files in P.
2559 @c ----------------------------------------------
2560 @node package Builder in aggregate projects
2561 @subsection package Builder in aggregate projects
2562 @c ----------------------------------------------
2564 As we mentioned before, only the package Builder can be specified in
2565 an aggregate project. In this package, only the following attributes
2570 @cindex @code{Switches}
2571 This attribute gives the list of switches to use for the builder
2572 (gprbuild or gnatmake), depending on the language of the main file.
2575 @smallexample @c projectfile
2576 for Switches ("Ada") use ("-d", "-p");
2577 for Switches ("C") use ("-p");
2580 These switches are only read from the main aggregate project (the
2581 one passed on the command line), and ignored in all other aggregate
2582 projects or projects.
2584 It can only contain builder switches, not compiler switches.
2586 @item @b{Global_Compilation_Switches}
2587 @cindex @code{Global_Compilation_Switches}
2589 This attribute gives the list of compiler switches for the various
2590 languages. For instance,
2592 @smallexample @c projectfile
2593 for Global_Compilation_Switches ("Ada") use ("-O1", "-g");
2594 for Global_Compilation_Switches ("C") use ("-O2");
2597 This attribute is only taken into account in the aggregate project
2598 specified on the command line, not in other aggregate projects.
2600 In the projects grouped by that aggregate, the attribute
2601 Builder.Global_Compilation_Switches is also ignored. However, the
2602 attribute Compiler.Default_Switches will be taken into account (but
2603 that of the aggregate have higher priority). The attribute
2604 Compiler.Switches is also taken into account and can be used to
2605 override the switches for a specific file. As a result, it always
2608 The rules are meant to avoid ambiguities when compiling. For
2609 instance, aggregate project Agg groups the projects A and B, that
2610 both depend on C. Here is an extra for all of these projects:
2612 @smallexample @c projectfile
2613 aggregate project Agg is
2614 for Project_Files use ("a.gpr", "b.gpr");
2616 for Global_Compilation_Switches ("Ada") use ("-O2");
2623 for Global_Compilation_Switches ("Ada") use ("-O1");
2628 for Default_Switches ("Ada") use ("-O1", "-g");
2629 for Switches ("a_file1.adb") use ("-O0");
2636 for Default_Switches ("Ada") use ("-O0");
2642 for Default_Switches ("Ada") use ("-O3", "-gnatn");
2643 for Switches ("c_file1.adb") use ("-O0", "-g");
2648 then the following switches are used:
2651 @item all files from project A except a_file1.adb are compiled
2652 with "-O2 -g", since the aggregate project has priority.
2653 @item the file a_file1.adb is compiled with
2654 "-O0", since the Compiler.Switches has priority
2655 @item all files from project B are compiled with
2656 "-O2", since the aggregate project has priority
2657 @item all files from C are compiled with "-O2 -gnatn", except for
2658 c_file1.adb which is compiled with "-O0 -g"
2661 Even though C is seen through two paths (through A and through
2662 B), the switches used by the compiler are unambiguous.
2664 @item @b{Global_Configuration_Pragmas}
2665 @cindex @code{Global_Configuration_Pragmas}
2667 This attribute can be used to specify a file containing
2668 configuration pragmas, to be passed to the compiler. Since we
2669 ignore the package Builder in other aggregate projects and projects,
2670 only those pragmas defined in the main aggregate project will be
2673 Projects can locally add to those by using the
2674 @code{Compiler.Local_Configuration_Pragmas} attribute if they need.
2678 For projects that are build through the aggregate, the package Builder
2679 is ignored, except for the Executable attribute which specifies the
2680 name of the executables resulting from the link of the main programs, and
2681 for the Executable_Suffix.
2683 @c ---------------------------------------------
2684 @node Aggregate Library Projects
2685 @section Aggregate Library Projects
2686 @c ---------------------------------------------
2690 Aggregate library projects make it possible to build a single library
2691 using object files built using other standard or library
2692 projects. This gives the flexibility to describe an application as
2693 having multiple modules (a GUI, database access, ...) using different
2694 project files (so possibly built with different compiler options) and
2695 yet create a single library (static or relocatable) out of the
2696 corresponding object files.
2699 * Building aggregate library projects::
2700 * Syntax of aggregate library projects::
2703 @c ---------------------------------------------
2704 @node Building aggregate library projects
2705 @subsection Building aggregate library projects
2706 @c ---------------------------------------------
2708 For example, we can define an aggregate project Agg that groups A, B
2711 @smallexample @c projectfile
2712 aggregate library project Agg is
2713 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2714 for Library_Name use ("agg");
2715 for Library_Dir use ("lagg");
2719 Then, when you build with:
2725 This will build all units from projects A, B and C and will create a
2726 static library named @file{libagg.a} into the @file{lagg}
2727 directory. An aggregate library project has the same set of
2728 restriction as a standard library project.
2730 Note that a shared aggregate library project cannot aggregates a
2731 static library project. In platforms where a compiler option is
2732 required to create relocatable object files, a Builder package in the
2733 aggregate library project may be used:
2735 @smallexample @c projectfile
2736 aggregate library project Agg is
2737 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2738 for Library_Name use ("agg");
2739 for Library_Dir use ("lagg");
2740 for Library_Kind use "relocatable";
2743 for Global_Compilation_Switches ("Ada") use ("-fPIC");
2748 With the above aggregate library Builder package, the @code{-fPIC}
2749 option will be passed to the compiler when building any source code
2750 from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}.
2752 @c ---------------------------------------------
2753 @node Syntax of aggregate library projects
2754 @subsection Syntax of aggregate library projects
2755 @c ---------------------------------------------
2757 An aggregate library project follows the general syntax of project
2758 files. The recommended extension is still @file{.gpr}. However, a special
2759 @code{aggregate library} qualifier must be put before the keyword
2762 An aggregate library project cannot @code{with} any other project
2763 (standard or aggregate), except an abstract project which can be used
2764 to share attribute values.
2766 An aggregate library project does not have any source files directly (only
2767 through other standard projects). Therefore a number of the standard
2768 attributes and packages are forbidden in an aggregate library
2769 project. Here is the (non exhaustive) list:
2773 @item Source_Files, Source_List_File and other attributes dealing with
2775 @item Source_Dirs, Exec_Dir and Object_Dir
2778 @item Externally_Built
2779 @item Inherit_Source_Path
2780 @item Excluded_Source_Dirs
2781 @item Locally_Removed_Files
2782 @item Excluded_Source_Files
2783 @item Excluded_Source_List_File
2787 The only package that is authorized (albeit optional) is Builder.
2789 The Project_Files attribute (See @pxref{Aggregate Projects}) is used to
2790 described the aggregated projects whose object files have to be
2791 included into the aggregate library.
2793 @c ---------------------------------------------
2794 @node Project File Reference
2795 @section Project File Reference
2796 @c ---------------------------------------------
2799 This section describes the syntactic structure of project files, the various
2800 constructs that can be used. Finally, it ends with a summary of all available
2804 * Project Declaration::
2805 * Qualified Projects::
2810 * Typed String Declaration::
2816 @c ---------------------------------------------
2817 @node Project Declaration
2818 @subsection Project Declaration
2819 @c ---------------------------------------------
2822 Project files have an Ada-like syntax. The minimal project file is:
2824 @smallexample @c projectfile
2832 The identifier @code{Empty} is the name of the project.
2833 This project name must be present after the reserved
2834 word @code{end} at the end of the project file, followed by a semi-colon.
2836 @b{Identifiers} (i.e.@: the user-defined names such as project or variable names)
2837 have the same syntax as Ada identifiers: they must start with a letter,
2838 and be followed by zero or more letters, digits or underscore characters;
2839 it is also illegal to have two underscores next to each other. Identifiers
2840 are always case-insensitive ("Name" is the same as "name").
2843 simple_name ::= identifier
2844 name ::= simple_name @{ . simple_name @}
2848 @b{Strings} are used for values of attributes or as indexes for these
2849 attributes. They are in general case sensitive, except when noted
2850 otherwise (in particular, strings representing file names will be case
2851 insensitive on some systems, so that "file.adb" and "File.adb" both
2852 represent the same file).
2854 @b{Reserved words} are the same as for standard Ada 95, and cannot
2855 be used for identifiers. In particular, the following words are currently
2856 used in project files, but others could be added later on. In bold are the
2857 extra reserved words in project files: @code{all, at, case, end, for, is,
2858 limited, null, others, package, renames, type, use, when, with, @b{extends},
2859 @b{external}, @b{project}}.
2861 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2862 hyphens through the end of the line.
2864 A project may be an @b{independent project}, entirely defined by a single
2865 project file. Any source file in an independent project depends only
2866 on the predefined library and other source files in the same project.
2867 But a project may also depend on other projects, either by importing them
2868 through @b{with clauses}, or by @b{extending} at most one other project. Both
2869 types of dependency can be used in the same project.
2871 A path name denotes a project file. It can be absolute or relative.
2872 An absolute path name includes a sequence of directories, in the syntax of
2873 the host operating system, that identifies uniquely the project file in the
2874 file system. A relative path name identifies the project file, relative
2875 to the directory that contains the current project, or relative to a
2876 directory listed in the environment variables ADA_PROJECT_PATH and
2877 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2878 operating system are case sensitive. As a special case, the directory
2879 separator can always be "/" even on Windows systems, so that project files
2880 can be made portable across architectures.
2881 The syntax of the environment variable ADA_PROJECT_PATH and
2882 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2883 semicolons on Windows.
2885 A given project name can appear only once in a context clause.
2887 It is illegal for a project imported by a context clause to refer, directly
2888 or indirectly, to the project in which this context clause appears (the
2889 dependency graph cannot contain cycles), except when one of the with clause
2890 in the cycle is a @b{limited with}.
2891 @c ??? Need more details here
2893 @smallexample @c projectfile
2894 with "other_project.gpr";
2895 project My_Project extends "extended.gpr" is
2900 These dependencies form a @b{directed graph}, potentially cyclic when using
2901 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
2904 A project's @b{immediate sources} are the source files directly defined by
2905 that project, either implicitly by residing in the project source directories,
2906 or explicitly through any of the source-related attributes.
2907 More generally, a project sources are the immediate sources of the project
2908 together with the immediate sources (unless overridden) of any
2909 project on which it depends directly or indirectly.
2911 A @b{project hierarchy} can be created, where projects are children of
2912 other projects. The name of such a child project must be @code{Parent.Child},
2913 where @code{Parent} is the name of the parent project. In particular, this
2914 makes all @code{with} clauses of the parent project automatically visible
2915 in the child project.
2918 project ::= context_clause project_declaration
2920 context_clause ::= @{with_clause@}
2921 with_clause ::= @i{with} path_name @{ , path_name @} ;
2922 path_name ::= string_literal
2924 project_declaration ::= simple_project_declaration | project_extension
2925 simple_project_declaration ::=
2926 @i{project} @i{<project_>}name @i{is}
2927 @{declarative_item@}
2928 @i{end} <project_>simple_name;
2931 @c ---------------------------------------------
2932 @node Qualified Projects
2933 @subsection Qualified Projects
2934 @c ---------------------------------------------
2937 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
2938 is identifiers or reserved words, to qualify the project.
2939 The current list of qualifiers is:
2942 @item @b{abstract}: qualifies a project with no sources. Such a
2943 project must either have no declaration of attributes @code{Source_Dirs},
2944 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
2945 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
2946 as empty. If it extends another project, the project it extends must also be a
2947 qualified abstract project.
2948 @item @b{standard}: a standard project is a non library project with sources.
2949 This is the default (implicit) qualifier.
2950 @item @b{aggregate}: a project whose sources are aggregated from other
2952 @item @b{aggregate library}: a library whose sources are aggregated
2953 from other project or library project files.
2954 @item @b{library}: a library project must declare both attributes
2955 @code{Library_Name} and @code{Library_Dir}.
2956 @item @b{configuration}: a configuration project cannot be in a project tree.
2957 It describes compilers and other tools to @code{gprbuild}.
2960 @c ---------------------------------------------
2962 @subsection Declarations
2963 @c ---------------------------------------------
2966 Declarations introduce new entities that denote types, variables, attributes,
2967 and packages. Some declarations can only appear immediately within a project
2968 declaration. Others can appear within a project or within a package.
2971 declarative_item ::= simple_declarative_item
2972 | typed_string_declaration
2973 | package_declaration
2975 simple_declarative_item ::= variable_declaration
2976 | typed_variable_declaration
2977 | attribute_declaration
2981 empty_declaration ::= @i{null} ;
2985 An empty declaration is allowed anywhere a declaration is allowed. It has
2988 @c ---------------------------------------------
2990 @subsection Packages
2991 @c ---------------------------------------------
2994 A project file may contain @b{packages}, that group attributes (typically
2995 all the attributes that are used by one of the GNAT tools).
2997 A package with a given name may only appear once in a project file.
2998 The following packages are currently supported in project files
2999 (See @pxref{Attributes} for the list of attributes that each can contain).
3003 This package specifies characteristics useful when invoking the binder either
3004 directly via the @command{gnat} driver or when using a builder such as
3005 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
3007 This package specifies the compilation options used when building an
3008 executable or a library for a project. Most of the options should be
3009 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
3010 but there are some general options that should be defined in this
3011 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
3014 This package specifies the options used when calling the checking tool
3015 @command{gnatcheck} via the @command{gnat} driver. Its attribute
3016 @b{Default_Switches} has the same semantics as for the package
3017 @code{Builder}. The first string should always be @code{-rules} to specify
3018 that all the other options belong to the @code{-rules} section of the
3019 parameters to @command{gnatcheck}.
3021 This package specifies the compilation options used by the compiler for
3022 each languages. @xref{Tools Options in Project Files}.
3023 @item Cross_Reference
3024 This package specifies the options used when calling the library tool
3025 @command{gnatxref} via the @command{gnat} driver. Its attributes
3026 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3027 package @code{Builder}.
3029 This package specifies the options used when calling the tool
3030 @command{gnatelim} via the @command{gnat} driver. Its attributes
3031 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3032 package @code{Builder}.
3034 This package specifies the options used when calling the search tool
3035 @command{gnatfind} via the @command{gnat} driver. Its attributes
3036 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3037 package @code{Builder}.
3039 This package the options to use when invoking @command{gnatls} via the
3040 @command{gnat} driver.
3042 This package specifies the options used when calling the tool
3043 @command{gnatstub} via the @command{gnat} driver. Its attributes
3044 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3045 package @code{Builder}.
3047 This package specifies the options used when starting an integrated
3048 development environment, for instance @command{GPS} or @command{Gnatbench}.
3049 @xref{The Development Environments}.
3051 This package specifies the options used by the linker.
3052 @xref{Main Subprograms}.
3054 @cindex Makefile package in projects
3055 This package is used by the GPS plugin Makefile.py. See the documentation
3056 in that plugin (from GPS: /Tools/Plug-ins).
3058 This package specifies the options used when calling the tool
3059 @command{gnatmetric} via the @command{gnat} driver. Its attributes
3060 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3061 package @code{Builder}.
3063 This package specifies the naming conventions that apply
3064 to the source files in a project. In particular, these conventions are
3065 used to automatically find all source files in the source directories,
3066 or given a file name to find out its language for proper processing.
3067 @xref{Naming Schemes}.
3068 @item Pretty_Printer
3069 This package specifies the options used when calling the formatting tool
3070 @command{gnatpp} via the @command{gnat} driver. Its attributes
3071 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3072 package @code{Builder}.
3074 This package specifies the options used when calling the tool
3075 @command{gnatstack} via the @command{gnat} driver. Its attributes
3076 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3077 package @code{Builder}.
3079 This package specifies the options used when calling the tool
3080 @command{gnatsync} via the @command{gnat} driver.
3084 In its simplest form, a package may be empty:
3086 @smallexample @c projectfile
3096 A package may contain @b{attribute declarations},
3097 @b{variable declarations} and @b{case constructions}, as will be
3100 When there is ambiguity between a project name and a package name,
3101 the name always designates the project. To avoid possible confusion, it is
3102 always a good idea to avoid naming a project with one of the
3103 names allowed for packages or any name that starts with @code{gnat}.
3105 A package can also be defined by a @b{renaming declaration}. The new package
3106 renames a package declared in a different project file, and has the same
3107 attributes as the package it renames. The name of the renamed package
3108 must be the same as the name of the renaming package. The project must
3109 contain a package declaration with this name, and the project
3110 must appear in the context clause of the current project, or be its parent
3111 project. It is not possible to add or override attributes to the renaming
3112 project. If you need to do so, you should use an @b{extending declaration}
3115 Packages that are renamed in other project files often come from project files
3116 that have no sources: they are just used as templates. Any modification in the
3117 template will be reflected automatically in all the project files that rename
3118 a package from the template. This is a very common way to share settings
3121 Finally, a package can also be defined by an @b{extending declaration}. This is
3122 similar to a @b{renaming declaration}, except that it is possible to add or
3123 override attributes.
3126 package_declaration ::= package_spec | package_renaming | package_extension
3128 @i{package} @i{<package_>}simple_name @i{is}
3129 @{simple_declarative_item@}
3130 @i{end} package_identifier ;
3131 package_renaming ::==
3132 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
3133 package_extension ::==
3134 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
3135 @{simple_declarative_item@}
3136 @i{end} package_identifier ;
3139 @c ---------------------------------------------
3141 @subsection Expressions
3142 @c ---------------------------------------------
3145 An expression is any value that can be assigned to an attribute or a
3146 variable. It is either a literal value, or a construct requiring runtime
3147 computation by the project manager. In a project file, the computed value of
3148 an expression is either a string or a list of strings.
3150 A string value is one of:
3152 @item A literal string, for instance @code{"comm/my_proj.gpr"}
3153 @item The name of a variable that evaluates to a string (@pxref{Variables})
3154 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
3155 @item An external reference (@pxref{External Values})
3156 @item A concatenation of the above, as in @code{"prefix_" & Var}.
3161 A list of strings is one of the following:
3164 @item A parenthesized comma-separated list of zero or more string expressions, for
3165 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
3166 @item The name of a variable that evaluates to a list of strings
3167 @item The name of an attribute that evaluates to a list of strings
3168 @item A concatenation of a list of strings and a string (as defined above), for
3169 instance @code{("A", "B") & "C"}
3170 @item A concatenation of two lists of strings
3175 The following is the grammar for expressions
3178 string_literal ::= "@{string_element@}" -- Same as Ada
3179 string_expression ::= string_literal
3182 | attribute_reference
3183 | ( string_expression @{ & string_expression @} )
3184 string_list ::= ( string_expression @{ , string_expression @} )
3185 | @i{string_variable}_name
3186 | @i{string_}attribute_reference
3187 term ::= string_expression | string_list
3188 expression ::= term @{ & term @} -- Concatenation
3192 Concatenation involves strings and list of strings. As soon as a list of
3193 strings is involved, the result of the concatenation is a list of strings. The
3194 following Ada declarations show the existing operators:
3196 @smallexample @c ada
3197 function "&" (X : String; Y : String) return String;
3198 function "&" (X : String_List; Y : String) return String_List;
3199 function "&" (X : String_List; Y : String_List) return String_List;
3203 Here are some specific examples:
3205 @smallexample @c projectfile
3207 List := () & File_Name; -- One string in this list
3208 List2 := List & (File_Name & ".orig"); -- Two strings
3209 Big_List := List & Lists2; -- Three strings
3210 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
3214 @c ---------------------------------------------
3215 @node External Values
3216 @subsection External Values
3217 @c ---------------------------------------------
3220 An external value is an expression whose value is obtained from the command
3221 that invoked the processing of the current project file (typically a
3222 gnatmake or gprbuild command).
3224 There are two kinds of external values, one that returns a single string, and
3225 one that returns a string list.
3227 The syntax of a single string external value is:
3230 external_value ::= @i{external} ( string_literal [, string_literal] )
3234 The first string_literal is the string to be used on the command line or
3235 in the environment to specify the external value. The second string_literal,
3236 if present, is the default to use if there is no specification for this
3237 external value either on the command line or in the environment.
3239 Typically, the external value will either exist in the
3240 ^environment variables^logical name^
3241 or be specified on the command line through the
3242 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
3243 are specified, then the command line value is used, so that a user can more
3244 easily override the value.
3246 The function @code{external} always returns a string. It is an error if the
3247 value was not found in the environment and no default was specified in the
3248 call to @code{external}.
3250 An external reference may be part of a string expression or of a string
3251 list expression, and can therefore appear in a variable declaration or
3252 an attribute declaration.
3254 Most of the time, this construct is used to initialize typed variables, which
3255 are then used in @b{case} statements to control the value assigned to
3256 attributes in various scenarios. Thus such variables are often called
3257 @b{scenario variables}.
3259 The syntax for a string list external value is:
3262 external_value ::= @i{external_as_list} ( string_literal , string_literal )
3266 The first string_literal is the string to be used on the command line or
3267 in the environment to specify the external value. The second string_literal is
3268 the separator between each component of the string list.
3270 If the external value does not exist in the environment or on the command line,
3271 the result is an empty list. This is also the case, if the separator is an
3272 empty string or if the external value is only one separator.
3274 Any separator at the beginning or at the end of the external value is
3275 discarded. Then, if there is no separator in the external value, the result is
3276 a string list with only one string. Otherwise, any string between the beginning
3277 and the first separator, between two consecutive separators and between the
3278 last separator and the end are components of the string list.
3281 @i{external_as_list} ("SWITCHES", ",")
3285 If the external value is "-O2,-g", the result is ("-O2", "-g").
3287 If the external value is ",-O2,-g,", the result is also ("-O2", "-g").
3289 if the external value is "-gnav", the result is ("-gnatv").
3291 If the external value is ",,", the result is ("").
3293 If the external value is ",", the result is (), the empty string list.
3295 @c ---------------------------------------------
3296 @node Typed String Declaration
3297 @subsection Typed String Declaration
3298 @c ---------------------------------------------
3301 A @b{type declaration} introduces a discrete set of string literals.
3302 If a string variable is declared to have this type, its value
3303 is restricted to the given set of literals. These are the only named
3304 types in project files. A string type may only be declared at the project
3305 level, not inside a package.
3308 typed_string_declaration ::=
3309 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
3313 The string literals in the list are case sensitive and must all be different.
3314 They may include any graphic characters allowed in Ada, including spaces.
3315 Here is an example of a string type declaration:
3317 @smallexample @c projectfile
3318 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
3322 Variables of a string type are called @b{typed variables}; all other
3323 variables are called @b{untyped variables}. Typed variables are
3324 particularly useful in @code{case} constructions, to support conditional
3325 attribute declarations. (@pxref{Case Statements}).
3327 A string type may be referenced by its name if it has been declared in the same
3328 project file, or by an expanded name whose prefix is the name of the project
3329 in which it is declared.
3331 @c ---------------------------------------------
3333 @subsection Variables
3334 @c ---------------------------------------------
3337 @b{Variables} store values (strings or list of strings) and can appear
3338 as part of an expression. The declaration of a variable creates the
3339 variable and assigns the value of the expression to it. The name of the
3340 variable is available immediately after the assignment symbol, if you
3341 need to reuse its old value to compute the new value. Before the completion
3342 of its first declaration, the value of a variable defaults to the empty
3345 A @b{typed} variable can be used as part of a @b{case} expression to
3346 compute the value, but it can only be declared once in the project file,
3347 so that all case statements see the same value for the variable. This
3348 provides more consistency and makes the project easier to understand.
3349 The syntax for its declaration is identical to the Ada syntax for an
3350 object declaration. In effect, a typed variable acts as a constant.
3352 An @b{untyped} variable can be declared and overridden multiple times
3353 within the same project. It is declared implicitly through an Ada
3354 assignment. The first declaration establishes the kind of the variable
3355 (string or list of strings) and successive declarations must respect
3356 the initial kind. Assignments are executed in the order in which they
3357 appear, so the new value replaces the old one and any subsequent reference
3358 to the variable uses the new value.
3360 A variable may be declared at the project file level, or within a package.
3363 typed_variable_declaration ::=
3364 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
3365 variable_declaration ::= @i{<variable_>}simple_name := expression;
3369 Here are some examples of variable declarations:
3371 @smallexample @c projectfile
3373 This_OS : OS := external ("OS"); -- a typed variable declaration
3374 That_OS := "GNU/Linux"; -- an untyped variable declaration
3376 Name := "readme.txt";
3377 Save_Name := Name & ".saved";
3380 List_With_One_Element := ("-gnaty");
3381 List_With_Two_Elements := List_With_One_Element & "-gnatg";
3382 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
3387 A @b{variable reference} may take several forms:
3390 @item The simple variable name, for a variable in the current package (if any)
3391 or in the current project
3392 @item An expanded name, whose prefix is a context name.
3397 A @b{context} may be one of the following:
3400 @item The name of an existing package in the current project
3401 @item The name of an imported project of the current project
3402 @item The name of an ancestor project (i.e., a project extended by the current
3403 project, either directly or indirectly)
3404 @item An expanded name whose prefix is an imported/parent project name, and
3405 whose selector is a package name in that project.
3408 @c ---------------------------------------------
3410 @subsection Attributes
3411 @c ---------------------------------------------
3414 A project (and its packages) may have @b{attributes} that define
3415 the project's properties. Some attributes have values that are strings;
3416 others have values that are string lists.
3419 attribute_declaration ::=
3420 simple_attribute_declaration | indexed_attribute_declaration
3421 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
3422 indexed_attribute_declaration ::=
3423 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
3424 attribute_designator ::=
3425 @i{<simple_attribute_>}simple_name
3426 | @i{<indexed_attribute_>}simple_name ( string_literal )
3430 There are two categories of attributes: @b{simple attributes}
3431 and @b{indexed attributes}.
3432 Each simple attribute has a default value: the empty string (for string
3433 attributes) and the empty list (for string list attributes).
3434 An attribute declaration defines a new value for an attribute, and overrides
3435 the previous value. The syntax of a simple attribute declaration is similar to
3436 that of an attribute definition clause in Ada.
3438 Some attributes are indexed. These attributes are mappings whose
3439 domain is a set of strings. They are declared one association
3440 at a time, by specifying a point in the domain and the corresponding image
3442 Like untyped variables and simple attributes, indexed attributes
3443 may be declared several times. Each declaration supplies a new value for the
3444 attribute, and replaces the previous setting.
3446 Here are some examples of attribute declarations:
3448 @smallexample @c projectfile
3449 -- simple attributes
3450 for Object_Dir use "objects";
3451 for Source_Dirs use ("units", "test/drivers");
3453 -- indexed attributes
3454 for Body ("main") use "Main.ada";
3455 for Switches ("main.ada") use ("-v", "-gnatv");
3456 for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
3458 -- indexed attributes copy (from package Builder in project Default)
3459 -- The package name must always be specified, even if it is the current
3461 for Default_Switches use Default.Builder'Default_Switches;
3465 Attributes references may be appear anywhere in expressions, and are used
3466 to retrieve the value previously assigned to the attribute. If an attribute
3467 has not been set in a given package or project, its value defaults to the
3468 empty string or the empty list.
3471 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
3472 attribute_prefix ::= @i{project}
3473 | @i{<project_>}simple_name
3474 | package_identifier
3475 | @i{<project_>}simple_name . package_identifier
3481 @smallexample @c projectfile
3483 Naming'Dot_Replacement
3484 Imported_Project'Source_Dirs
3485 Imported_Project.Naming'Casing
3486 Builder'Default_Switches ("Ada")
3490 The prefix of an attribute may be:
3493 @item @code{project} for an attribute of the current project
3494 @item The name of an existing package of the current project
3495 @item The name of an imported project
3496 @item The name of a parent project that is extended by the current project
3497 @item An expanded name whose prefix is imported/parent project name,
3498 and whose selector is a package name
3503 Legal attribute names are listed below, including the package in
3504 which they must be declared. These names are case-insensitive. The
3505 semantics for the attributes is explained in great details in other sections.
3507 The column @emph{index} indicates whether the attribute is an indexed attribute,
3508 and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the
3509 system (file). The text is between brackets ([]) if the index is optional.
3511 @multitable @columnfractions .3 .1 .2 .4
3512 @headitem Attribute Name @tab Value @tab Package @tab Index
3513 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
3514 @item Name @tab string @tab - @tab (Read-only, name of project)
3515 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
3516 @item Source_Files @tab list @tab - @tab -
3517 @item Source_Dirs @tab list @tab - @tab -
3518 @item Source_List_File @tab string @tab - @tab -
3519 @item Locally_Removed_Files @tab list @tab - @tab -
3520 @item Excluded_Source_Files @tab list @tab - @tab -
3521 @item Object_Dir @tab string @tab - @tab -
3522 @item Exec_Dir @tab string @tab - @tab -
3523 @item Excluded_Source_Dirs @tab list @tab - @tab -
3524 @item Excluded_Source_Files @tab list @tab - @tab -
3525 @item Excluded_Source_List_File @tab list @tab - @tab -
3526 @item Inherit_Source_Path @tab list @tab - @tab insensitive
3527 @item Languages @tab list @tab - @tab -
3528 @item Main @tab list @tab - @tab -
3529 @item Main_Language @tab string @tab - @tab -
3530 @item Externally_Built @tab string @tab - @tab -
3531 @item Roots @tab list @tab - @tab file
3533 Library-related attributes @tab @tab @tab @pxref{Library Projects}
3534 @item Library_Dir @tab string @tab - @tab -
3535 @item Library_Name @tab string @tab - @tab -
3536 @item Library_Kind @tab string @tab - @tab -
3537 @item Library_Version @tab string @tab - @tab -
3538 @item Library_Interface @tab string @tab - @tab -
3539 @item Library_Auto_Init @tab string @tab - @tab -
3540 @item Library_Options @tab list @tab - @tab -
3541 @item Leading_Library_Options @tab list @tab - @tab -
3542 @item Library_Src_Dir @tab string @tab - @tab -
3543 @item Library_ALI_Dir @tab string @tab - @tab -
3544 @item Library_GCC @tab string @tab - @tab -
3545 @item Library_Symbol_File @tab string @tab - @tab -
3546 @item Library_Symbol_Policy @tab string @tab - @tab -
3547 @item Library_Reference_Symbol_File @tab string @tab - @tab -
3548 @item Interfaces @tab list @tab - @tab -
3550 Naming @tab @tab @tab @pxref{Naming Schemes}
3551 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
3552 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
3553 @item Separate_Suffix @tab string @tab Naming @tab -
3554 @item Casing @tab string @tab Naming @tab -
3555 @item Dot_Replacement @tab string @tab Naming @tab -
3556 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
3557 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
3558 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
3559 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
3561 Building @tab @tab @tab @pxref{Switches and Project Files}
3562 @item Default_Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE @tab insensitive (language name)
3563 @item Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack @tab [file] (file name)
3564 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
3565 @item Local_Config_File @tab string @tab insensitive @tab -
3566 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
3567 @item Global_Compilation_Switches @tab list @tab Builder @tab language
3568 @item Executable @tab string @tab Builder @tab [file]
3569 @item Executable_Suffix @tab string @tab Builder @tab -
3570 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
3572 IDE (used and created by GPS) @tab @tab @tab
3573 @item Remote_Host @tab string @tab IDE @tab -
3574 @item Program_Host @tab string @tab IDE @tab -
3575 @item Communication_Protocol @tab string @tab IDE @tab -
3576 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
3577 @item Debugger_Command @tab string @tab IDE @tab -
3578 @item Gnatlist @tab string @tab IDE @tab -
3579 @item Gnat @tab string @tab IDE @tab -
3580 @item VCS_Kind @tab string @tab IDE @tab -
3581 @item VCS_File_Check @tab string @tab IDE @tab -
3582 @item VCS_Log_Check @tab string @tab IDE @tab -
3583 @item Documentation_Dir @tab string @tab IDE @tab -
3585 Configuration files @tab @tab @tab See gprbuild manual
3586 @item Default_Language @tab string @tab - @tab -
3587 @item Run_Path_Option @tab list @tab - @tab -
3588 @item Run_Path_Origin @tab string @tab - @tab -
3589 @item Separate_Run_Path_Options @tab string @tab - @tab -
3590 @item Toolchain_Version @tab string @tab - @tab insensitive
3591 @item Toolchain_Description @tab string @tab - @tab insensitive
3592 @item Object_Generated @tab string @tab - @tab insensitive
3593 @item Objects_Linked @tab string @tab - @tab insensitive
3594 @item Target @tab string @tab - @tab -
3595 @item Library_Builder @tab string @tab - @tab -
3596 @item Library_Support @tab string @tab - @tab -
3597 @item Archive_Builder @tab list @tab - @tab -
3598 @item Archive_Builder_Append_Option @tab list @tab - @tab -
3599 @item Archive_Indexer @tab list @tab - @tab -
3600 @item Archive_Suffix @tab string @tab - @tab -
3601 @item Library_Partial_Linker @tab list @tab - @tab -
3602 @item Shared_Library_Prefix @tab string @tab - @tab -
3603 @item Shared_Library_Suffix @tab string @tab - @tab -
3604 @item Symbolic_Link_Supported @tab string @tab - @tab -
3605 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
3606 @item Library_Auto_Init_Supported @tab string @tab - @tab -
3607 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
3608 @item Library_Version_Switches @tab list @tab - @tab -
3609 @item Library_Install_Name_Option @tab string @tab - @tab -
3610 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
3611 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
3612 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
3613 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
3614 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3615 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3616 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
3617 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
3618 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
3619 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
3620 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
3621 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitive (language)
3622 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
3623 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
3624 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
3625 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
3626 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
3627 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3628 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3629 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
3630 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3631 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3632 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
3633 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
3634 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
3635 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
3636 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
3637 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
3638 @item Prefix @tab string @tab Binder @tab insensitive (language)
3639 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
3640 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
3641 @item Linker_Options @tab list @tab Linker @tab -
3642 @item Leading_Switches @tab list @tab Linker @tab -
3643 @item Map_File_Options @tab string @tab Linker @tab -
3644 @item Executable_Switches @tab list @tab Linker @tab -
3645 @item Lib_Dir_Switch @tab string @tab Linker @tab -
3646 @item Lib_Name_Switch @tab string @tab Linker @tab -
3647 @item Max_Command_Line_Length @tab string @tab Linker @tab -
3648 @item Response_File_Format @tab string @tab Linker @tab -
3649 @item Response_File_Switches @tab list @tab Linker @tab -
3652 @c ---------------------------------------------
3653 @node Case Statements
3654 @subsection Case Statements
3655 @c ---------------------------------------------
3658 A @b{case} statement is used in a project file to effect conditional
3659 behavior. Through this statement, you can set the value of attributes
3660 and variables depending on the value previously assigned to a typed
3663 All choices in a choice list must be distinct. Unlike Ada, the choice
3664 lists of all alternatives do not need to include all values of the type.
3665 An @code{others} choice must appear last in the list of alternatives.
3667 The syntax of a @code{case} construction is based on the Ada case statement
3668 (although the @code{null} statement for empty alternatives is optional).
3670 The case expression must be a typed string variable, whose value is often
3671 given by an external reference (@pxref{External Values}).
3673 Each alternative starts with the reserved word @code{when}, either a list of
3674 literal strings separated by the @code{"|"} character or the reserved word
3675 @code{others}, and the @code{"=>"} token.
3676 Each literal string must belong to the string type that is the type of the
3678 After each @code{=>}, there are zero or more statements. The only
3679 statements allowed in a case construction are other case statements,
3680 attribute declarations and variable declarations. String type declarations and
3681 package declarations are not allowed. Variable declarations are restricted to
3682 variables that have already been declared before the case construction.
3686 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
3689 @i{when} discrete_choice_list =>
3691 | attribute_declaration
3692 | variable_declaration
3693 | empty_declaration@}
3695 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
3699 Here is a typical example:
3701 @smallexample @c projectfile
3704 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
3705 OS : OS_Type := external ("OS", "GNU/Linux");
3709 when "GNU/Linux" | "Unix" =>
3710 for Switches ("Ada") use ("-gnath");
3712 for Switches ("Ada") use ("-gnatP");
3721 @c ---------------------------------------------
3722 @node Tools Supporting Project Files
3723 @chapter Tools Supporting Project Files
3724 @c ---------------------------------------------
3729 * gnatmake and Project Files::
3730 * The GNAT Driver and Project Files::
3731 * The Development Environments::
3734 @c ---------------------------------------------
3735 @node gnatmake and Project Files
3736 @section gnatmake and Project Files
3737 @c ---------------------------------------------
3740 This section covers several topics related to @command{gnatmake} and
3741 project files: defining ^switches^switches^ for @command{gnatmake}
3742 and for the tools that it invokes; specifying configuration pragmas;
3743 the use of the @code{Main} attribute; building and rebuilding library project
3747 * Switches Related to Project Files::
3748 * Switches and Project Files::
3749 * Specifying Configuration Pragmas::
3750 * Project Files and Main Subprograms::
3751 * Library Project Files::
3754 @c ---------------------------------------------
3755 @node Switches Related to Project Files
3756 @subsection Switches Related to Project Files
3757 @c ---------------------------------------------
3760 The following switches are used by GNAT tools that support project files:
3764 @item ^-P^/PROJECT_FILE=^@var{project}
3765 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
3766 Indicates the name of a project file. This project file will be parsed with
3767 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
3768 if any, and using the external references indicated
3769 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
3771 There may zero, one or more spaces between @option{-P} and @var{project}.
3774 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3776 Since the Project Manager parses the project file only after all the switches
3777 on the command line are checked, the order of the switches
3778 @option{^-P^/PROJECT_FILE^},
3779 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3780 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3782 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3783 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3784 Indicates that external variable @var{name} has the value @var{value}.
3785 The Project Manager will use this value for occurrences of
3786 @code{external(name)} when parsing the project file.
3789 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3797 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3798 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3799 @var{name}, only the last one is used.
3801 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3802 takes precedence over the value of the same name in the environment.
3804 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3805 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3806 Indicates the verbosity of the parsing of GNAT project files.
3809 @option{-vP0} means Default;
3810 @option{-vP1} means Medium;
3811 @option{-vP2} means High.
3815 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3819 The default is ^Default^DEFAULT^: no output for syntactically correct
3821 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3822 only the last one is used.
3824 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3825 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3826 Add directory <dir> at the beginning of the project search path, in order,
3827 after the current working directory.
3831 @cindex @option{-eL} (any project-aware tool)
3832 Follow all symbolic links when processing project files.
3835 @item ^--subdirs^/SUBDIRS^=<subdir>
3836 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3837 This switch is recognized by gnatmake and gnatclean. It indicate that the real
3838 directories (except the source directories) are the subdirectories <subdir>
3839 of the directories specified in the project files. This applies in particular
3840 to object directories, library directories and exec directories. If the
3841 subdirectories do not exist, they are created automatically.
3845 @c ---------------------------------------------
3846 @node Switches and Project Files
3847 @subsection Switches and Project Files
3848 @c ---------------------------------------------
3852 It is not currently possible to specify VMS style qualifiers in the project
3853 files; only Unix style ^switches^switches^ may be specified.
3856 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3857 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3858 attribute, a @code{Switches} attribute, or both;
3859 as their names imply, these ^switch^switch^-related
3860 attributes affect the ^switches^switches^ that are used for each of these GNAT
3862 @command{gnatmake} is invoked. As will be explained below, these
3863 component-specific ^switches^switches^ precede
3864 the ^switches^switches^ provided on the @command{gnatmake} command line.
3866 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3867 indexed by language name (case insensitive) whose value is a string list.
3870 @smallexample @c projectfile
3873 for ^Default_Switches^Default_Switches^ ("Ada")
3874 use ("^-gnaty^-gnaty^",
3881 The @code{Switches} attribute is indexed on a file name (which may or may
3882 not be case sensitive, depending
3883 on the operating system) whose value is a string list. For example:
3885 @smallexample @c projectfile
3888 for Switches ("main1.adb")
3890 for Switches ("main2.adb")
3897 For the @code{Builder} package, the file names must designate source files
3898 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
3899 file names must designate @file{ALI} or source files for main subprograms.
3900 In each case just the file name without an explicit extension is acceptable.
3902 For each tool used in a program build (@command{gnatmake}, the compiler, the
3903 binder, and the linker), the corresponding package @dfn{contributes} a set of
3904 ^switches^switches^ for each file on which the tool is invoked, based on the
3905 ^switch^switch^-related attributes defined in the package.
3906 In particular, the ^switches^switches^
3907 that each of these packages contributes for a given file @var{f} comprise:
3910 @item the value of attribute @code{Switches (@var{f})},
3911 if it is specified in the package for the given file,
3912 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
3913 if it is specified in the package.
3918 If neither of these attributes is defined in the package, then the package does
3919 not contribute any ^switches^switches^ for the given file.
3921 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
3922 two sets, in the following order: those contributed for the file
3923 by the @code{Builder} package;
3924 and the switches passed on the command line.
3926 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
3927 the ^switches^switches^ passed to the tool comprise three sets,
3928 in the following order:
3932 the applicable ^switches^switches^ contributed for the file
3933 by the @code{Builder} package in the project file supplied on the command line;
3936 those contributed for the file by the package (in the relevant project file --
3937 see below) corresponding to the tool; and
3940 the applicable switches passed on the command line.
3943 The term @emph{applicable ^switches^switches^} reflects the fact that
3944 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
3945 tools, depending on the individual ^switch^switch^.
3947 @command{gnatmake} may invoke the compiler on source files from different
3948 projects. The Project Manager will use the appropriate project file to
3949 determine the @code{Compiler} package for each source file being compiled.
3950 Likewise for the @code{Binder} and @code{Linker} packages.
3952 As an example, consider the following package in a project file:
3954 @smallexample @c projectfile
3958 for ^Default_Switches^Default_Switches^ ("Ada")
3960 for Switches ("a.adb")
3962 for Switches ("b.adb")
3971 If @command{gnatmake} is invoked with this project file, and it needs to
3972 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
3973 @file{a.adb} will be compiled with the ^switch^switch^
3975 @file{b.adb} with ^switches^switches^
3977 and @option{^-gnaty^-gnaty^},
3978 and @file{c.adb} with @option{^-g^-g^}.
3980 The following example illustrates the ordering of the ^switches^switches^
3981 contributed by different packages:
3983 @smallexample @c projectfile
3987 for Switches ("main.adb")
3996 for Switches ("main.adb")
4004 If you issue the command:
4007 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
4011 then the compiler will be invoked on @file{main.adb} with the following
4012 sequence of ^switches^switches^
4015 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
4019 with the last @option{^-O^-O^}
4020 ^switch^switch^ having precedence over the earlier ones;
4021 several other ^switches^switches^
4022 (such as @option{^-c^-c^}) are added implicitly.
4024 The ^switches^switches^
4026 and @option{^-O1^-O1^} are contributed by package
4027 @code{Builder}, @option{^-O2^-O2^} is contributed
4028 by the package @code{Compiler}
4029 and @option{^-O0^-O0^} comes from the command line.
4031 The @option{^-g^-g^}
4032 ^switch^switch^ will also be passed in the invocation of
4035 A final example illustrates switch contributions from packages in different
4038 @smallexample @c projectfile
4041 for Source_Files use ("pack.ads", "pack.adb");
4043 for ^Default_Switches^Default_Switches^ ("Ada")
4044 use ("^-gnata^-gnata^");
4052 for Source_Files use ("foo_main.adb", "bar_main.adb");
4054 for Switches ("foo_main.adb")
4064 procedure Foo_Main is
4073 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
4077 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
4078 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
4079 @option{^-gnato^-gnato^} (passed on the command line).
4080 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
4081 are @option{^-g^-g^} from @code{Proj4.Builder},
4082 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
4083 and @option{^-gnato^-gnato^} from the command line.
4085 When using @command{gnatmake} with project files, some ^switches^switches^ or
4086 arguments may be expressed as relative paths. As the working directory where
4087 compilation occurs may change, these relative paths are converted to absolute
4088 paths. For the ^switches^switches^ found in a project file, the relative paths
4089 are relative to the project file directory, for the switches on the command
4090 line, they are relative to the directory where @command{gnatmake} is invoked.
4091 The ^switches^switches^ for which this occurs are:
4097 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
4099 ^-o^-o^, object files specified in package @code{Linker} or after
4100 -largs on the command line). The exception to this rule is the ^switch^switch^
4101 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
4103 @c ---------------------------------------------
4104 @node Specifying Configuration Pragmas
4105 @subsection Specifying Configuration Pragmas
4106 @c ---------------------------------------------
4109 When using @command{gnatmake} with project files, if there exists a file
4110 @file{gnat.adc} that contains configuration pragmas, this file will be
4113 Configuration pragmas can be defined by means of the following attributes in
4114 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
4115 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
4117 Both these attributes are single string attributes. Their values is the path
4118 name of a file containing configuration pragmas. If a path name is relative,
4119 then it is relative to the project directory of the project file where the
4120 attribute is defined.
4122 When compiling a source, the configuration pragmas used are, in order,
4123 those listed in the file designated by attribute
4124 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
4125 project file, if it is specified, and those listed in the file designated by
4126 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
4127 the project file of the source, if it exists.
4129 @c ---------------------------------------------
4130 @node Project Files and Main Subprograms
4131 @subsection Project Files and Main Subprograms
4132 @c ---------------------------------------------
4135 When using a project file, you can invoke @command{gnatmake}
4136 with one or several main subprograms, by specifying their source files on the
4140 gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb
4144 Each of these needs to be a source file of the same project, except
4145 when the switch ^-u^/UNIQUE^ is used.
4147 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
4148 same project, one of the project in the tree rooted at the project specified
4149 on the command line. The package @code{Builder} of this common project, the
4150 "main project" is the one that is considered by @command{gnatmake}.
4152 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
4153 imported directly or indirectly by the project specified on the command line.
4154 Note that if such a source file is not part of the project specified on the
4155 command line, the ^switches^switches^ found in package @code{Builder} of the
4156 project specified on the command line, if any, that are transmitted
4157 to the compiler will still be used, not those found in the project file of
4160 When using a project file, you can also invoke @command{gnatmake} without
4161 explicitly specifying any main, and the effect depends on whether you have
4162 defined the @code{Main} attribute. This attribute has a string list value,
4163 where each element in the list is the name of a source file (the file
4164 extension is optional) that contains a unit that can be a main subprogram.
4166 If the @code{Main} attribute is defined in a project file as a non-empty
4167 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
4168 line, then invoking @command{gnatmake} with this project file but without any
4169 main on the command line is equivalent to invoking @command{gnatmake} with all
4170 the file names in the @code{Main} attribute on the command line.
4173 @smallexample @c projectfile
4176 for Main use ("main1.adb", "main2.adb", "main3.adb");
4182 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
4184 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}.
4186 When the project attribute @code{Main} is not specified, or is specified
4187 as an empty string list, or when the switch @option{-u} is used on the command
4188 line, then invoking @command{gnatmake} with no main on the command line will
4189 result in all immediate sources of the project file being checked, and
4190 potentially recompiled. Depending on the presence of the switch @option{-u},
4191 sources from other project files on which the immediate sources of the main
4192 project file depend are also checked and potentially recompiled. In other
4193 words, the @option{-u} switch is applied to all of the immediate sources of the
4196 When no main is specified on the command line and attribute @code{Main} exists
4197 and includes several mains, or when several mains are specified on the
4198 command line, the default ^switches^switches^ in package @code{Builder} will
4199 be used for all mains, even if there are specific ^switches^switches^
4200 specified for one or several mains.
4202 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
4203 the specific ^switches^switches^ for each main, if they are specified.
4205 @c ---------------------------------------------
4206 @node Library Project Files
4207 @subsection Library Project Files
4208 @c ---------------------------------------------
4211 When @command{gnatmake} is invoked with a main project file that is a library
4212 project file, it is not allowed to specify one or more mains on the command
4215 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
4216 ^-l^/ACTION=LINK^ have special meanings.
4219 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
4220 to @command{gnatmake} that @command{gnatbind} should be invoked for the
4223 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
4224 to @command{gnatmake} that the binder generated file should be compiled
4225 (in the case of a stand-alone library) and that the library should be built.
4228 @c ---------------------------------------------
4229 @node The GNAT Driver and Project Files
4230 @section The GNAT Driver and Project Files
4231 @c ---------------------------------------------
4234 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
4235 can benefit from project files:
4236 (@command{^gnatbind^gnatbind^},
4237 @command{^gnatcheck^gnatcheck^},
4238 @command{^gnatclean^gnatclean^},
4239 @command{^gnatelim^gnatelim^},
4240 @command{^gnatfind^gnatfind^},
4241 @command{^gnatlink^gnatlink^},
4242 @command{^gnatls^gnatls^},
4243 @command{^gnatmetric^gnatmetric^},
4244 @command{^gnatpp^gnatpp^},
4245 @command{^gnatstub^gnatstub^},
4246 and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
4247 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
4248 They must be invoked through the @command{gnat} driver.
4250 The @command{gnat} driver is a wrapper that accepts a number of commands and
4251 calls the corresponding tool. It was designed initially for VMS platforms (to
4252 convert VMS qualifiers to Unix-style switches), but it is now available on all
4255 On non-VMS platforms, the @command{gnat} driver accepts the following commands
4259 @item BIND to invoke @command{^gnatbind^gnatbind^}
4260 @item CHOP to invoke @command{^gnatchop^gnatchop^}
4261 @item CLEAN to invoke @command{^gnatclean^gnatclean^}
4262 @item COMP or COMPILE to invoke the compiler
4263 @item ELIM to invoke @command{^gnatelim^gnatelim^}
4264 @item FIND to invoke @command{^gnatfind^gnatfind^}
4265 @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
4266 @item LINK to invoke @command{^gnatlink^gnatlink^}
4267 @item LS or LIST to invoke @command{^gnatls^gnatls^}
4268 @item MAKE to invoke @command{^gnatmake^gnatmake^}
4269 @item NAME to invoke @command{^gnatname^gnatname^}
4270 @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
4271 @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
4272 @item METRIC to invoke @command{^gnatmetric^gnatmetric^}
4273 @item STUB to invoke @command{^gnatstub^gnatstub^}
4274 @item XREF to invoke @command{^gnatxref^gnatxref^}
4279 (note that the compiler is invoked using the command
4280 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
4282 On non-VMS platforms, between @command{gnat} and the command, two
4283 special switches may be used:
4286 @item @command{-v} to display the invocation of the tool.
4287 @item @command{-dn} to prevent the @command{gnat} driver from removing
4288 the temporary files it has created. These temporary files are
4289 configuration files and temporary file list files.
4294 The command may be followed by switches and arguments for the invoked
4298 gnat bind -C main.ali
4304 Switches may also be put in text files, one switch per line, and the text
4305 files may be specified with their path name preceded by '@@'.
4308 gnat bind @@args.txt main.ali
4312 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
4313 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
4314 (@option{^-P^/PROJECT_FILE^},
4315 @option{^-X^/EXTERNAL_REFERENCE^} and
4316 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
4317 the switches of the invoking tool.
4319 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
4320 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
4321 the immediate sources of the specified project file.
4323 When GNAT METRIC is used with a project file, but with no source
4324 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
4325 with all the immediate sources of the specified project file and with
4326 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
4329 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
4330 a project file, no source is specified on the command line and
4331 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
4332 the underlying tool (^gnatpp^gnatpp^ or
4333 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
4334 not only for the immediate sources of the main project.
4336 (-U stands for Universal or Union of the project files of the project tree)
4339 For each of the following commands, there is optionally a corresponding
4340 package in the main project.
4343 @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
4345 @item package @code{Check} for command CHECK (invoking
4346 @code{^gnatcheck^gnatcheck^})
4348 @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
4350 @item package @code{Cross_Reference} for command XREF (invoking
4351 @code{^gnatxref^gnatxref^})
4353 @item package @code{Eliminate} for command ELIM (invoking
4354 @code{^gnatelim^gnatelim^})
4356 @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
4358 @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
4360 @item package @code{Gnatstub} for command STUB
4361 (invoking @code{^gnatstub^gnatstub^})
4363 @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
4365 @item package @code{Check} for command CHECK
4366 (invoking @code{^gnatcheck^gnatcheck^})
4368 @item package @code{Metrics} for command METRIC
4369 (invoking @code{^gnatmetric^gnatmetric^})
4371 @item package @code{Pretty_Printer} for command PP or PRETTY
4372 (invoking @code{^gnatpp^gnatpp^})
4377 Package @code{Gnatls} has a unique attribute @code{Switches},
4378 a simple variable with a string list value. It contains ^switches^switches^
4379 for the invocation of @code{^gnatls^gnatls^}.
4381 @smallexample @c projectfile
4394 All other packages have two attribute @code{Switches} and
4395 @code{^Default_Switches^Default_Switches^}.
4397 @code{Switches} is an indexed attribute, indexed by the
4398 source file name, that has a string list value: the ^switches^switches^ to be
4399 used when the tool corresponding to the package is invoked for the specific
4402 @code{^Default_Switches^Default_Switches^} is an attribute,
4403 indexed by the programming language that has a string list value.
4404 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
4405 ^switches^switches^ for the invocation of the tool corresponding
4406 to the package, except if a specific @code{Switches} attribute
4407 is specified for the source file.
4409 @smallexample @c projectfile
4413 for Source_Dirs use ("**");
4424 for ^Default_Switches^Default_Switches^ ("Ada")
4425 use ("^-gnatv^-gnatv^",
4426 "^-gnatwa^-gnatwa^");
4432 for ^Default_Switches^Default_Switches^ ("Ada")
4440 for ^Default_Switches^Default_Switches^ ("Ada")
4442 for Switches ("main.adb")
4451 for ^Default_Switches^Default_Switches^ ("Ada")
4458 package Cross_Reference is
4459 for ^Default_Switches^Default_Switches^ ("Ada")
4464 end Cross_Reference;
4470 With the above project file, commands such as
4473 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
4474 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
4475 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
4476 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
4477 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
4481 will set up the environment properly and invoke the tool with the switches
4482 found in the package corresponding to the tool:
4483 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
4484 except @code{Switches ("main.adb")}
4485 for @code{^gnatlink^gnatlink^}.
4486 It is also possible to invoke some of the tools,
4487 (@code{^gnatcheck^gnatcheck^},
4488 @code{^gnatmetric^gnatmetric^},
4489 and @code{^gnatpp^gnatpp^})
4490 on a set of project units thanks to the combination of the switches
4491 @option{-P}, @option{-U} and possibly the main unit when one is interested
4492 in its closure. For instance,
4498 will compute the metrics for all the immediate units of project
4501 gnat metric -Pproj -U
4505 will compute the metrics for all the units of the closure of projects
4506 rooted at @code{proj}.
4508 gnat metric -Pproj -U main_unit
4512 will compute the metrics for the closure of units rooted at
4513 @code{main_unit}. This last possibility relies implicitly
4514 on @command{gnatbind}'s option @option{-R}. But if the argument files for the
4515 tool invoked by the @command{gnat} driver are explicitly specified
4516 either directly or through the tool @option{-files} option, then the tool
4517 is called only for these explicitly specified files.
4519 @c ---------------------------------------------
4520 @node The Development Environments
4521 @section The Development Environments
4522 @c ---------------------------------------------
4525 See the appropriate manuals for more details. These environments will
4526 store a number of settings in the project itself, when they are meant
4527 to be shared by the whole team working on the project. Here are the
4528 attributes defined in the package @b{IDE} in projects.
4532 This is a simple attribute. Its value is a string that designates the remote
4533 host in a cross-compilation environment, to be used for remote compilation and
4534 debugging. This field should not be specified when running on the local
4538 This is a simple attribute. Its value is a string that specifies the
4539 name of IP address of the embedded target in a cross-compilation environment,
4540 on which the program should execute.
4542 @item Communication_Protocol
4543 This is a simple string attribute. Its value is the name of the protocol
4544 to use to communicate with the target in a cross-compilation environment,
4545 e.g.@: @code{"wtx"} or @code{"vxworks"}.
4547 @item Compiler_Command
4548 This is an associative array attribute, whose domain is a language name. Its
4549 value is string that denotes the command to be used to invoke the compiler.
4550 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
4551 gnatmake, in particular in the handling of switches.
4553 @item Debugger_Command
4554 This is simple attribute, Its value is a string that specifies the name of
4555 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
4557 @item Default_Switches
4558 This is an associative array attribute. Its indexes are the name of the
4559 external tools that the GNAT Programming System (GPS) is supporting. Its
4560 value is a list of switches to use when invoking that tool.
4563 This is a simple attribute. Its value is a string that specifies the name
4564 of the @command{gnatls} utility to be used to retrieve information about the
4565 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
4568 This is a simple attribute. Its value is a string used to specify the
4569 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
4570 ClearCase or Perforce.
4573 This is a simple attribute. Its value is a string that specifies the name
4574 of the @command{gnat} utility to be used when executing various tools from
4575 GPS, in particular @code{"gnat pp"}, @code{"gnat stub"},@dots{}
4577 @item VCS_File_Check
4578 This is a simple attribute. Its value is a string that specifies the
4579 command used by the VCS to check the validity of a file, either
4580 when the user explicitly asks for a check, or as a sanity check before
4584 This is a simple attribute. Its value is a string that specifies
4585 the command used by the VCS to check the validity of a log file.
4587 @item VCS_Repository_Root
4588 The VCS repository root path. This is used to create tags or branches
4589 of the repository. For subversion the value should be the @code{URL}
4590 as specified to check-out the working copy of the repository.
4592 @item VCS_Patch_Root
4593 The local root directory to use for building patch file. All patch chunks
4594 will be relative to this path. The root project directory is used if
4595 this value is not defined.