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::
230 * Distributed support::
233 @c ---------------------------------------------
234 @node Source Files and Directories
235 @subsection Source Files and Directories
236 @c ---------------------------------------------
239 When you create a new project, the first thing to describe is how to find the
240 corresponding source files. This is the only settings that are needed by all
241 the tools that will use this project (builder, compiler, binder and linker for
242 the compilation, IDEs to edit the source files,@dots{}).
244 @cindex Source directories
245 First step is to declare the source directories, which are the directories
246 to be searched to find source files. In the case of the example,
247 the @file{common} directory is the only source directory.
249 @cindex @code{Source_Dirs}
250 There are several ways of defining source directories:
253 @item When the attribute @b{Source_Dirs} is not used, a project contains a
254 single source directory which is the one where the project file itself
255 resides. In our example, if @file{build.gpr} is placed in the @file{common}
256 directory, the project has the needed implicit source directory.
258 @item The attribute @b{Source_Dirs} can be set to a list of path names, one
259 for each of the source directories. Such paths can either be absolute
260 names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the
261 directory in which the project file resides (for instance "." if
262 @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
263 Each of the source directories must exist and be readable.
266 The syntax for directories is platform specific. For portability, however,
267 the project manager will always properly translate UNIX-like path names to
268 the native format of specific platform. For instance, when the same project
269 file is to be used both on Unix and Windows, "/" should be used as the
270 directory separator rather than "\".
272 @item The attribute @b{Source_Dirs} can automatically include subdirectories
273 using a special syntax inspired by some UNIX shells. If any of the path in
274 the list ends with @emph{"**"}, then that path and all its subdirectories
275 (recursively) are included in the list of source directories. For instance,
276 @file{**} and @file{./**} represent the complete directory tree rooted at ".".
277 @cindex Source directories, recursive
279 @cindex @code{Excluded_Source_Dirs}
280 When using that construct, it can sometimes be convenient to also use the
281 attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry
282 specifies a directory whose immediate content, not including subdirs, is to
283 be excluded. It is also possible to exclude a complete directory subtree
284 using the "**" notation.
286 @cindex @code{Ignore_Source_Sub_Dirs}
287 It is often desirable to remove, from the source directories, directory
288 subtrees rooted at some subdirectories. An example is the subdirectories
289 created by a Version Control System such as Subversion that creates directory
290 subtrees rooted at subdirectories ".svn". To do that, attribute
291 @b{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple
292 file names for the roots of these undesirable directory subtrees.
295 @b{for} Source_Dirs @b{use} ("./**");
296 @b{for} Ignore_Source_Sub_Dirs @b{use} (".svn");
302 When applied to the simple example, and because we generally prefer to have
303 the project file at the toplevel directory rather than mixed with the sources,
304 we will create the following file
308 @b{project} Build @b{is}
309 @b{for} Source_Dirs @b{use} ("common"); -- <<<<
314 Once source directories have been specified, one may need to indicate
315 source files of interest. By default, all source files present in the source
316 directories are considered by the project manager. When this is not desired,
317 it is possible to specify the list of sources to consider explicitly.
318 In such a case, only source file base names are indicated and not
319 their absolute or relative path names. The project manager is in charge of
320 locating the specified source files in the specified source directories.
323 @item By default, the project manager search for all source files of all
324 specified languages in all the source directories.
326 Since the project manager was initially developed for Ada environments, the
327 default language is usually Ada and the above project file is complete: it
328 defines without ambiguity the sources composing the project: that is to say,
329 all the sources in subdirectory "common" for the default language (Ada) using
330 the default naming convention.
332 @cindex @code{Languages}
333 However, when compiling a multi-language application, or a pure C
334 application, the project manager must be told which languages are of
335 interest, which is done by setting the @b{Languages} attribute to a list of
336 strings, each of which is the name of a language. Tools like
337 @command{gnatmake} only know about Ada, while other tools like
338 @command{gprbuild} know about many more languages such as C, C++, Fortran,
339 assembly and others can be added dynamically.
341 @cindex Naming scheme
342 Even when using only Ada, the default naming might not be suitable. Indeed,
343 how does the project manager recognizes an "Ada file" from any other
344 file? Project files can describe the naming scheme used for source files,
345 and override the default (@pxref{Naming Schemes}). The default is the
346 standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
347 specs), which is what is used in our example, explaining why no naming scheme
348 is explicitly specified.
349 @xref{Naming Schemes}.
351 @item @code{Source_Files}
352 @cindex @code{Source_Files}
353 In some cases, source directories might contain files that should not be
354 included in a project. One can specify the explicit list of file names to
355 be considered through the @b{Source_Files} attribute.
356 When this attribute is defined, instead of looking at every file in the
357 source directories, the project manager takes only those names into
358 consideration reports errors if they cannot be found in the source
359 directories or does not correspond to the naming scheme.
361 @item For various reasons, it is sometimes useful to have a project with no
362 sources (most of the time because the attributes defined in the project
363 file will be reused in other projects, as explained in @pxref{Organizing
364 Projects into Subsystems}. To do this, the attribute
365 @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
366 @emph{Source_Dirs} can be set to the empty list, with the same
369 @item @code{Source_List_File}
370 @cindex @code{Source_List_File}
371 If there is a great number of files, it might be more convenient to use
372 the attribute @b{Source_List_File}, which specifies the full path of a file.
373 This file must contain a list of source file names (one per line, no
374 directory information) that are searched as if they had been defined
375 through @emph{Source_Files}. Such a file can easily be created through
378 A warning is issued if both attributes @code{Source_Files} and
379 @code{Source_List_File} are given explicit values. In this case, the
380 attribute @code{Source_Files} prevails.
382 @item @code{Excluded_Source_Files}
383 @cindex @code{Excluded_Source_Files}
384 @cindex @code{Locally_Removed_Files}
385 @cindex @code{Excluded_Source_List_File}
386 Specifying an explicit list of files is not always convenient.It might be
387 more convenient to use the default search rules with specific exceptions.
388 This can be done thanks to the attribute @b{Excluded_Source_Files}
389 (or its synonym @b{Locally_Removed_Files}).
390 Its value is the list of file names that should not be taken into account.
391 This attribute is often used when extending a project, @xref{Project
392 Extension}. A similar attribute @b{Excluded_Source_List_File} plays the same
393 role but takes the name of file containing file names similarly to
394 @code{Source_List_File}.
399 In most simple cases, such as the above example, the default source file search
400 behavior provides the expected result, and we do not need to add anything after
401 setting @code{Source_Dirs}. The project manager automatically finds
402 @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the
405 Note that it is considered an error for a project file to have no sources
406 attached to it unless explicitly declared as mentioned above.
408 If the order of the source directories is known statically, that is if
409 @code{"**"} is not used in the string list @code{Source_Dirs}, then there may
410 be several files with the same source file name sitting in different
411 directories of the project. In this case, only the file in the first directory
412 is considered as a source of the project and the others are hidden. If
413 @code{"**"} is used in the string list @code{Source_Dirs}, it is an error
414 to have several files with the same source file name in the same directory
415 @code{"**"} subtree, since there would be an ambiguity as to which one should
416 be used. However, two files with the same source file name may exist in two
417 single directories or directory subtrees. In this case, the one in the first
418 directory or directory subtree is a source of the project.
420 @c ---------------------------------------------
421 @node Object and Exec Directory
422 @subsection Object and Exec Directory
423 @c ---------------------------------------------
426 The next step when writing a project is to indicate where the compiler should
427 put the object files. In fact, the compiler and other tools might create
428 several different kind of files (for GNAT, there is the object file and the ALI
429 file for instance). One of the important concepts in projects is that most
430 tools may consider source directories as read-only and do not attempt to create
431 new or temporary files there. Instead, all files are created in the object
432 directory. It is of course not true for project-aware IDEs, whose purpose it is
433 to create the source files.
435 @cindex @code{Object_Dir}
436 The object directory is specified through the @b{Object_Dir} attribute.
437 Its value is the path to the object directory, either absolute or
438 relative to the directory containing the project file. This
439 directory must already exist and be readable and writable, although
440 some tools have a switch to create the directory if needed (See
441 the switch @code{-p} for @command{gnatmake} and @command{gprbuild}).
443 If the attribute @code{Object_Dir} is not specified, it defaults to
444 the project directory, that is the directory containing the project file.
446 For our example, we can specify the object dir in this way:
449 @b{project} Build @b{is}
450 @b{for} Source_Dirs @b{use} ("common");
451 @b{for} Object_Dir @b{use} "obj"; -- <<<<
456 As mentioned earlier, there is a single object directory per project. As a
457 result, if you have an existing system where the object files are spread in
458 several directories, you can either move all of them into the same directory if
459 you want to build it with a single project file, or study the section on
460 subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
461 separate object directory can be associated with one of the subsystem
462 constituting the application.
464 When the @command{linker} is called, it usually creates an executable. By
465 default, this executable is placed in the object directory of the project. It
466 might be convenient to store it in its own directory.
468 @cindex @code{Exec_Dir}
469 This can be done through the @code{Exec_Dir} attribute, which, like
470 @emph{Object_Dir} contains a single absolute or relative path and must point to
471 an existing and writable directory, unless you ask the tool to create it on
472 your behalf. When not specified, It defaults to the object directory and
473 therefore to the project file's directory if neither @emph{Object_Dir} nor
474 @emph{Exec_Dir} was specified.
476 In the case of the example, let's place the executable in the root
477 of the hierarchy, ie the same directory as @file{build.gpr}. Hence
478 the project file is now
481 @b{project} Build @b{is}
482 @b{for} Source_Dirs @b{use} ("common");
483 @b{for} Object_Dir @b{use} "obj";
484 @b{for} Exec_Dir @b{use} "."; -- <<<<
488 @c ---------------------------------------------
489 @node Main Subprograms
490 @subsection Main Subprograms
491 @c ---------------------------------------------
494 In the previous section, executables were mentioned. The project manager needs
495 to be taught what they are. In a project file, an executable is indicated by
496 pointing to source file of the main subprogram. In C this is the file that
497 contains the @code{main} function, and in Ada the file that contains the main
500 There can be any number of such main files within a given project, and thus
501 several executables can be built in the context of a single project file. Of
502 course, one given executable might not (and in fact will not) need all the
503 source files referenced by the project. As opposed to other build environments
504 such as @command{makefile}, one does not need to specify the list of
505 dependencies of each executable, the project-aware builders knows enough of the
506 semantics of the languages to build ands link only the necessary elements.
509 The list of main files is specified via the @b{Main} attribute. It contains
510 a list of file names (no directories). If a project defines this
511 attribute, it is not necessary to identify main files on the
512 command line when invoking a builder, and editors like
513 @command{GPS} will be able to create extra menus to spawn or debug the
514 corresponding executables.
517 @b{project} Build @b{is}
518 @b{for} Source_Dirs @b{use} ("common");
519 @b{for} Object_Dir @b{use} "obj";
520 @b{for} Exec_Dir @b{use} ".";
521 @b{for} Main @b{use} ("proc.adb"); -- <<<<
526 If this attribute is defined in the project, then spawning the builder
527 with a command such as
530 gnatmake ^-Pbuild^/PROJECT_FILE=build^
534 automatically builds all the executables corresponding to the files
535 listed in the @emph{Main} attribute. It is possible to specify one
536 or more executables on the command line to build a subset of them.
538 @c ---------------------------------------------
539 @node Tools Options in Project Files
540 @subsection Tools Options in Project Files
541 @c ---------------------------------------------
544 We now have a project file that fully describes our environment, and can be
545 used to build the application with a simple @command{gnatmake} command as seen
546 in the previous section. In fact, the empty project we showed immediately at
547 the beginning (with no attribute at all) could already fulfill that need if it
548 was put in the @file{common} directory.
550 Of course, we always want more control. This section will show you how to
551 specify the compilation switches that the various tools involved in the
552 building of the executable should use.
554 @cindex command line length
555 Since source names and locations are described into the project file, it is not
556 necessary to use switches on the command line for this purpose (switches such
557 as -I for gcc). This removes a major source of command line length overflow.
558 Clearly, the builders will have to communicate this information one way or
559 another to the underlying compilers and tools they call but they usually use
560 response files for this and thus should not be subject to command line
563 Several tools are participating to the creation of an executable: the compiler
564 produces object files from the source files; the binder (in the Ada case)
565 creates an source file that takes care, among other things, of elaboration
566 issues and global variables initialization; and the linker gathers everything
567 into a single executable that users can execute. All these tools are known by
568 the project manager and will be called with user defined switches from the
569 project files. However, we need to introduce a new project file concept to
570 express which switches to be used for any of the tools involved in the build.
572 @cindex project file packages
573 A project file is subdivided into zero or more @b{packages}, each of which
574 contains the attributes specific to one tool (or one set of tools). Project
575 files use an Ada-like syntax for packages. Package names permitted in project
576 files are restricted to a predefined set (@pxref{Packages}), and the contents
577 of packages are limited to a small set of constructs and attributes
578 (@pxref{Attributes}).
580 Our example project file can be extended with the following empty packages. At
581 this stage, they could all be omitted since they are empty, but they show which
582 packages would be involved in the build process.
585 @b{project} Build @b{is}
586 @b{for} Source_Dirs @b{use} ("common");
587 @b{for} Object_Dir @b{use} "obj";
588 @b{for} Exec_Dir @b{use} ".";
589 @b{for} Main @b{use} ("proc.adb");
591 @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
594 @b{package} Compiler @b{is} --<<< for the compiler
597 @b{package} Binder @b{is} --<<< for the binder
600 @b{package} Linker @b{is} --<<< for the linker
606 Let's first examine the compiler switches. As stated in the initial description
607 of the example, we want to compile all files with @option{-O2}. This is a
608 compiler switch, although it is usual, on the command line, to pass it to the
609 builder which then passes it to the compiler. It is recommended to use directly
610 the right package, which will make the setup easier to understand for other
613 Several attributes can be used to specify the switches:
616 @item @b{Default_Switches}:
617 @cindex @code{Default_Switches}
618 This is the first mention in this manual of an @b{indexed attribute}. When
619 this attribute is defined, one must supply an @emph{index} in the form of a
621 In the case of @emph{Default_Switches}, the index is the name of the
622 language to which the switches apply (since a different compiler will
623 likely be used for each language, and each compiler has its own set of
624 switches). The value of the attribute is a list of switches.
626 In this example, we want to compile all Ada source files with the
627 @option{-O2} switch, and the resulting project file is as follows
628 (only the @code{Compiler} package is shown):
631 @b{package} Compiler @b{is}
632 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
637 @cindex @code{Switches}
638 in some cases, we might want to use specific switches
639 for one or more files. For instance, compiling @file{proc.adb} might not be
640 possible at high level of optimization because of a compiler issue.
641 In such a case, the @emph{Switches}
642 attribute (indexed on the file name) can be used and will override the
643 switches defined by @emph{Default_Switches}. Our project file would
647 @b{package} Compiler @b{is}
648 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
649 @b{for} Switches ("proc.adb") @b{use} ("-O0");
654 @code{Switches} may take a pattern as an index, such as in:
657 @b{package} Compiler @b{is}
658 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
659 @b{for} Switches ("pkg*") @b{use} ("-O0");
664 Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0,
668 @code{Switches} can also be given a language name as index instead of a file
669 name in which case it has the same semantics as @emph{Default_Switches}.
670 However, indexes with wild cards are never valid for language name.
672 @item @b{Local_Configuration_Pragmas}:
673 @cindex @code{Local_Configuration_Pragmas}
674 this attribute may specify the path
675 of a file containing configuration pragmas for use by the Ada compiler,
676 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
677 used for all the sources of the project.
681 The switches for the other tools are defined in a similar manner through the
682 @b{Default_Switches} and @b{Switches} attributes, respectively in the
683 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
684 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
685 package (for linking executables).
687 @c ---------------------------------------------
688 @node Compiling with Project Files
689 @subsection Compiling with Project Files
690 @c ---------------------------------------------
693 Now that our project files are written, let's build our executable.
694 Here is the command we would use from the command line:
697 gnatmake ^-Pbuild^/PROJECT_FILE=build^
701 This will automatically build the executables specified through the
702 @emph{Main} attribute: for each, it will compile or recompile the
703 sources for which the object file does not exist or is not up-to-date; it
704 will then run the binder; and finally run the linker to create the
707 @command{gnatmake} only knows how to handle Ada files. By using
708 @command{gprbuild} as a builder, you could automatically manage C files the
709 same way: create the file @file{utils.c} in the @file{common} directory,
710 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
713 gprbuild ^-Pbuild^/PROJECT_FILE=build^
717 Gprbuild knows how to recompile the C files and will
718 recompile them only if one of their dependencies has changed. No direct
719 indication on how to build the various elements is given in the
720 project file, which describes the project properties rather than a
721 set of actions to be executed. Here is the invocation of
722 @command{gprbuild} when building a multi-language program:
735 Notice the three steps described earlier:
738 @item The first three gcc commands correspond to the compilation phase.
739 @item The gprbind command corresponds to the post-compilation phase.
740 @item The last gcc command corresponds to the final link.
745 @cindex @option{-v} option (for GPRbuild)
746 The default output of GPRbuild's execution is kept reasonably simple and easy
747 to understand. In particular, some of the less frequently used commands are not
748 shown, and some parameters are abbreviated. So it is not possible to rerun the
749 effect of the @command{gprbuild} command by cut-and-pasting its output.
750 GPRbuild's option @code{-v} provides a much more verbose output which includes,
751 among other information, more complete compilation, post-compilation and link
754 @c ---------------------------------------------
755 @node Executable File Names
756 @subsection Executable File Names
757 @c ---------------------------------------------
760 @cindex @code{Executable}
761 By default, the executable name corresponding to a main file is
762 computed from the main source file name. Through the attribute
763 @b{Builder.Executable}, it is possible to change this default.
765 For instance, instead of building @command{proc} (or @command{proc.exe}
766 on Windows), we could configure our project file to build "proc1"
767 (resp proc1.exe) with the following addition:
769 @smallexample @c projectfile
771 ... -- same as before
773 for Executable ("proc.adb") use "proc1";
779 @cindex @code{Executable_Suffix}
780 Attribute @b{Executable_Suffix}, when specified, may change the suffix
781 of the executable files, when no attribute @code{Executable} applies:
782 its value replace the platform-specific executable suffix.
783 The default executable suffix is empty on UNIX and ".exe" on Windows.
785 It is also possible to change the name of the produced executable by using the
786 command line switch @option{-o}. When several mains are defined in the project,
787 it is not possible to use the @option{-o} switch and the only way to change the
788 names of the executable is provided by Attributes @code{Executable} and
789 @code{Executable_Suffix}.
791 @c ---------------------------------------------
792 @node Avoid Duplication With Variables
793 @subsection Avoid Duplication With Variables
794 @c ---------------------------------------------
797 To illustrate some other project capabilities, here is a slightly more complex
798 project using similar sources and a main program in C:
800 @smallexample @c projectfile
802 for Languages use ("Ada", "C");
803 for Source_Dirs use ("common");
804 for Object_Dir use "obj";
805 for Main use ("main.c");
807 C_Switches := ("-pedantic");
808 for Default_Switches ("C") use C_Switches;
809 for Default_Switches ("Ada") use ("-gnaty");
810 for Switches ("main.c") use C_Switches & ("-g");
816 This project has many similarities with the previous one.
817 As expected, its @code{Main} attribute now refers to a C source.
818 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
819 executable will be put in the directory @file{obj}.
821 The most noticeable difference is the use of a variable in the
822 @emph{Compiler} package to store settings used in several attributes.
823 This avoids text duplication, and eases maintenance (a single place to
824 modify if we want to add new switches for C files). We will revisit
825 the use of variables in the context of scenarios (@pxref{Scenarios in
828 In this example, we see how the file @file{main.c} can be compiled with
829 the switches used for all the other C files, plus @option{-g}.
830 In this specific situation the use of a variable could have been
831 replaced by a reference to the @code{Default_Switches} attribute:
833 @smallexample @c projectfile
834 for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
838 Note the tick (@emph{'}) used to refer to attributes defined in a package.
840 Here is the output of the GPRbuild command using this project:
844 gcc -c -pedantic -g main.c
845 gcc -c -gnaty proc.adb
846 gcc -c -gnaty pack.adb
847 gcc -c -pedantic utils.c
854 The default switches for Ada sources,
855 the default switches for C sources (in the compilation of @file{lib.c}),
856 and the specific switches for @file{main.c} have all been taken into
859 @c ---------------------------------------------
861 @subsection Naming Schemes
862 @c ---------------------------------------------
865 Sometimes an Ada software system is ported from one compilation environment to
866 another (say GNAT), and the file are not named using the default GNAT
867 conventions. Instead of changing all the file names, which for a variety of
868 reasons might not be possible, you can define the relevant file naming scheme
869 in the @b{Naming} package of your project file.
871 The naming scheme has two distinct goals for the project manager: it
872 allows finding of source files when searching in the source
873 directories, and given a source file name it makes it possible to guess
874 the associated language, and thus the compiler to use.
876 Note that the use by the Ada compiler of pragmas Source_File_Name is not
877 supported when using project files. You must use the features described in this
878 paragraph. You can however specify other configuration pragmas
879 (@pxref{Specifying Configuration Pragmas}).
881 The following attributes can be defined in package @code{Naming}:
885 @cindex @code{Casing}
886 Its value must be one of @code{"lowercase"} (the default if
887 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
888 casing of file names with regards to the Ada unit name. Given an Ada unit
889 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
890 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
891 On Windows, file names are case insensitive, so this attribute is
894 @item @b{Dot_Replacement}:
895 @cindex @code{Dot_Replacement}
896 This attribute specifies the string that should replace the "." in unit
897 names. Its default value is @code{"-"} so that a unit
898 @code{Parent.Child} is expected to be found in the file
899 @file{parent-child.adb}. The replacement string must satisfy the following
900 requirements to avoid ambiguities in the naming scheme:
903 @item It must not be empty
904 @item It cannot start or end with an alphanumeric character
905 @item It cannot be a single underscore
906 @item It cannot start with an underscore followed by an alphanumeric
907 @item It cannot contain a dot @code{'.'} except if the entire string
912 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
913 @cindex @code{Spec_Suffix}
914 @cindex @code{Specification_Suffix}
915 For Ada, these attributes give the suffix used in file names that contain
916 specifications. For other languages, they give the extension for files
917 that contain declaration (header files in C for instance). The attribute
918 is indexed on the language.
919 The two attributes are equivalent, but the latter is obsolescent.
920 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
921 @code{"^.ads^.ADS^"}.
922 The value must satisfy the following requirements:
925 @item It must not be empty
926 @item It cannot start with an alphanumeric character
927 @item It cannot start with an underscore followed by an alphanumeric character
928 @item It must include at least one dot
932 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
933 @cindex @code{Body_Suffix}
934 @cindex @code{Implementation_Suffix}
935 These attributes give the extension used for file names that contain
936 code (bodies in Ada). They are indexed on the language. The second
937 version is obsolescent and fully replaced by the first attribute.
939 These attributes must satisfy the same requirements as @code{Spec_Suffix}.
940 In addition, they must be different from any of the values in
942 If @code{Body_Suffix ("Ada")} is not specified, then the default is
943 @code{"^.adb^.ADB^"}.
945 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
946 same string, then a file name that ends with the longest of these two
947 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
948 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
950 If the suffix does not start with a '.', a file with a name exactly equal
951 to the suffix will also be part of the project (for instance if you define
952 the suffix as @code{Makefile}, a file called @file{Makefile} will be part
953 of the project. This capability is usually not interesting when building.
954 However, it might become useful when a project is also used to
955 find the list of source files in an editor, like the GNAT Programming System
958 @item @b{Separate_Suffix}:
959 @cindex @code{Separate_Suffix}
960 This attribute is specific to Ada. It denotes the suffix used in file names
961 that contain separate bodies. If it is not specified, then it defaults to
962 same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the
963 @code{Body_Suffix} attribute. The only accepted index is "Ada".
965 @item @b{Spec} or @b{Specification}:
967 @cindex @code{Specification}
968 This attribute @code{Spec} can be used to define the source file name for a
969 given Ada compilation unit's spec. The index is the literal name of the Ada
970 unit (case insensitive). The value is the literal base name of the file that
971 contains this unit's spec (case sensitive or insensitive depending on the
972 operating system). This attribute allows the definition of exceptions to the
973 general naming scheme, in case some files do not follow the usual
976 When a source file contains several units, the relative position of the unit
977 can be indicated. The first unit in the file is at position 1
979 @smallexample @c projectfile
980 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
981 for Spec ("top") use "foo.a" at 1;
982 for Spec ("foo") use "foo.a" at 2;
985 @item @b{Body} or @b{Implementation}:
987 @cindex @code{Implementation}
988 These attribute play the same role as @emph{Spec} for Ada bodies.
990 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
991 @cindex @code{Specification_Exceptions}
992 @cindex @code{Implementation_Exceptions}
993 These attributes define exceptions to the naming scheme for languages
994 other than Ada. They are indexed on the language name, and contain
995 a list of file names respectively for headers and source code.
1000 For example, the following package models the Apex file naming rules:
1002 @smallexample @c projectfile
1005 for Casing use "lowercase";
1006 for Dot_Replacement use ".";
1007 for Spec_Suffix ("Ada") use ".1.ada";
1008 for Body_Suffix ("Ada") use ".2.ada";
1015 For example, the following package models the DEC Ada file naming rules:
1017 @smallexample @c projectfile
1020 for Casing use "lowercase";
1021 for Dot_Replacement use "__";
1022 for Spec_Suffix ("Ada") use "_.ada";
1023 for Body_Suffix ("Ada") use ".ada";
1029 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1030 names in lower case)
1033 @c ---------------------------------------------
1035 @subsection Installation
1036 @c ---------------------------------------------
1039 After building an application or a library it is often required to
1040 install it into the development environment. For instance this step is
1041 required if the library is to be used by another application.
1042 The @command{gprinstall} tool provides an easy way to install
1043 libraries, executable or object code generated during the build. The
1044 @b{Install} package can be used to change the default locations.
1046 The following attributes can be defined in package @code{Install}:
1052 Whether the project is to be installed, values are @code{true}
1053 (default) or @code{false}.
1056 @cindex @code{Prefix}
1058 Root directory for the installation.
1060 @item @b{Exec_Subdir}
1062 Subdirectory of @b{Prefix} where executables are to be
1063 installed. Default is @b{bin}.
1065 @item @b{Lib_Subdir}
1067 Subdirectory of @b{Prefix} where directory with the library or object
1068 files is to be installed. Default is @b{lib}.
1070 @item @b{Sources_Subdir}
1072 Subdirectory of @b{Prefix} where directory with sources is to be
1073 installed. Default is @b{include}.
1075 @item @b{Project_Subdir}
1077 Subdirectory of @b{Prefix} where the generated project file is to be
1078 installed. Default is @b{share/gpr}.
1081 @c ---------------------------------------------
1082 @node Distributed support
1083 @subsection Distributed support
1084 @c ---------------------------------------------
1087 For large projects the compilation time can become a limitation in
1088 the development cycle. To cope with that, GPRbuild supports
1089 distributed compilation.
1091 The following attributes can be defined in package @code{Remote}:
1095 @item @b{Build_Slaves}
1096 @cindex @code{Build_Slaves}
1098 A list of string referencing the remote build slaves to use for the
1099 compilation phase. The format is:
1100 @code{[protocol://]name.domain[:port]}.
1102 Where @code{protocol} is one of:
1107 @cindex @code{rsync}
1109 The sources are copied using the external @code{rsync} tool.
1113 The sources are accessed via a shared directory or mount point.
1117 The default port used to communicate with @command{gprslave} is
1121 @cindex @code{Root_Dir}
1123 Root directory of the project's sources. The default value is the
1124 project's directory.
1128 @c ---------------------------------------------
1129 @node Organizing Projects into Subsystems
1130 @section Organizing Projects into Subsystems
1131 @c ---------------------------------------------
1134 A @b{subsystem} is a coherent part of the complete system to be built. It is
1135 represented by a set of sources and one single object directory. A system can
1136 be composed of a single subsystem when it is simple as we have seen in the
1137 first section. Complex systems are usually composed of several interdependent
1138 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1139 other one is required to build it, and in particular if visibility on some of
1140 the sources of this other subsystem is required. Each subsystem is usually
1141 represented by its own project file.
1143 In this section, the previous example is being extended. Let's assume some
1144 sources of our @code{Build} project depend on other sources.
1145 For instance, when building a graphical interface, it is usual to depend upon
1146 a graphical library toolkit such as GtkAda. Furthermore, we also need
1147 sources from a logging module we had previously written.
1150 * Project Dependencies::
1151 * Cyclic Project Dependencies::
1152 * Sharing Between Projects::
1153 * Global Attributes::
1156 @c ---------------------------------------------
1157 @node Project Dependencies
1158 @subsection Project Dependencies
1159 @c ---------------------------------------------
1162 GtkAda comes with its own project file (appropriately called
1163 @file{gtkada.gpr}), and we will assume we have already built a project
1164 called @file{logging.gpr} for the logging module. With the information provided
1165 so far in @file{build.gpr}, building the application would fail with an error
1166 indicating that the gtkada and logging units that are relied upon by the sources
1167 of this project cannot be found.
1169 This is easily solved by adding the following @b{with} clauses at the beginning
1172 @smallexample @c projectfile
1174 with "a/b/logging.gpr";
1181 @cindex @code{Externally_Built}
1182 When such a project is compiled, @command{gnatmake} will automatically
1183 check the other projects and recompile their sources when needed. It will also
1184 recompile the sources from @code{Build} when needed, and finally create the
1185 executable. In some cases, the implementation units needed to recompile a
1186 project are not available, or come from some third-party and you do not want to
1187 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1188 "true" can be set, indicating to the builder that this project can be assumed
1189 to be up-to-date, and should not be considered for recompilation. In Ada, if
1190 the sources of this externally built project were compiled with another version
1191 of the compiler or with incompatible options, the binder will issue an error.
1193 The project's @code{with} clause has several effects. It provides source
1194 visibility between projects during the compilation process. It also guarantees
1195 that the necessary object files from @code{Logging} and @code{GtkAda} are
1196 available when linking @code{Build}.
1198 As can be seen in this example, the syntax for importing projects is similar
1199 to the syntax for importing compilation units in Ada. However, project files
1200 use literal strings instead of names, and the @code{with} clause identifies
1201 project files rather than packages.
1203 Each literal string after @code{with} is the path
1204 (absolute or relative) to a project file. The @code{.gpr} extension is
1205 optional, although we recommend adding it. If no extension is specified,
1206 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1207 the file is searched for exactly as written in the @code{with} clause,
1208 that is with no extension.
1210 As mentioned above, the path after a @code{with} has to be a literal
1211 string, and you cannot use concatenation, or lookup the value of external
1212 variables to change the directories from which a project is loaded.
1213 A solution if you need something like this is to use aggregate projects
1214 (@pxref{Aggregate Projects}).
1216 @cindex project path
1217 When a relative path or a base name is used, the
1218 project files are searched relative to each of the directories in the
1219 @b{project path}. This path includes all the directories found with the
1220 following algorithm, in that order, as soon as a matching file is found,
1224 @item First, the file is searched relative to the directory that contains the
1225 current project file.
1228 @cindex @code{ADA_PROJECT_PATH}
1229 @cindex @code{GPR_PROJECT_PATH}
1230 Then it is searched relative to all the directories specified in the
1231 ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and
1232 @b{ADA_PROJECT_PATH} (in that order) if they exist. The former is
1233 recommended, the latter is kept for backward compatibility.
1235 @item Finally, it is searched relative to the default project directories.
1236 Such directories depends on the tool used. The different locations searched
1237 in the specified order are:
1240 @item @file{<prefix>/<target>/lib/gnat}
1241 (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
1242 @option{--target} is specified)
1243 @item @file{<prefix>/share/gpr/}
1244 (for @command{gnatmake} and @command{gprbuild})
1245 @item @file{<prefix>/lib/gnat/}
1246 (for @command{gnatmake} and @command{gprbuild})
1249 In our example, @file{gtkada.gpr} is found in the predefined directory if
1250 it was installed at the same root as GNAT.
1254 Some tools also support extending the project path from the command line,
1255 generally through the @option{-aP}. You can see the value of the project
1256 path by using the @command{gnatls -v} command.
1258 Any symbolic link will be fully resolved in the directory of the
1259 importing project file before the imported project file is examined.
1261 Any source file in the imported project can be used by the sources of the
1262 importing project, transitively.
1263 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1264 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1265 import @code{C} explicitly. However, this is not recommended, because if
1266 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1267 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1268 that will report such indirect dependencies.
1270 One very important aspect of a project hierarchy is that
1271 @b{a given source can only belong to one project} (otherwise the project manager
1272 would not know which settings apply to it and when to recompile it). It means
1273 that different project files do not usually share source directories or
1274 when they do, they need to specify precisely which project owns which sources
1275 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1276 can each own a source with the same base file name as long as they live in
1277 different directories. The latter is not true for Ada Sources because of the
1278 correlation between source files and Ada units.
1280 @c ---------------------------------------------
1281 @node Cyclic Project Dependencies
1282 @subsection Cyclic Project Dependencies
1283 @c ---------------------------------------------
1286 Cyclic dependencies are mostly forbidden:
1287 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1288 is not allowed to import @code{A}. However, there are cases when cyclic
1289 dependencies would be beneficial. For these cases, another form of import
1290 between projects exists: the @b{limited with}. A project @code{A} that
1291 imports a project @code{B} with a straight @code{with} may also be imported,
1292 directly or indirectly, by @code{B} through a @code{limited with}.
1294 The difference between straight @code{with} and @code{limited with} is that
1295 the name of a project imported with a @code{limited with} cannot be used in the
1296 project importing it. In particular, its packages cannot be renamed and
1297 its variables cannot be referred to.
1299 @smallexample @c 0projectfile
1303 For Exec_Dir use B'Exec_Dir; -- ok
1306 limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
1308 For Exec_Dir use A'Exec_Dir; -- not ok
1315 limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
1317 For Exec_Dir use A'Exec_Dir; -- not ok
1321 @c ---------------------------------------------
1322 @node Sharing Between Projects
1323 @subsection Sharing Between Projects
1324 @c ---------------------------------------------
1327 When building an application, it is common to have similar needs in several of
1328 the projects corresponding to the subsystems under construction. For instance,
1329 they will all have the same compilation switches.
1331 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1332 switches for all sources of a subsystem is simple: it is just a matter of
1333 adding a @code{Compiler.Default_Switches} attribute to each project files with
1334 the same value. Of course, that means duplication of data, and both places need
1335 to be changed in order to recompile the whole application with different
1336 switches. It can become a real problem if there are many subsystems and thus
1337 many project files to edit.
1339 There are two main approaches to avoiding this duplication:
1342 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1343 to reference the attribute in Logging, either through a package renaming,
1344 or by referencing the attribute. The following example shows both cases:
1346 @smallexample @c projectfile
1349 for Switches ("Ada") use ("-O2");
1352 for Switches ("Ada") use ("-E");
1358 package Compiler renames Logging.Compiler;
1360 for Switches ("Ada") use Logging.Binder'Switches ("Ada");
1366 The solution used for @code{Compiler} gets the same value for all
1367 attributes of the package, but you cannot modify anything from the
1368 package (adding extra switches or some exceptions). The second
1369 version is more flexible, but more verbose.
1371 If you need to refer to the value of a variable in an imported
1372 project, rather than an attribute, the syntax is similar but uses
1373 a "." rather than an apostrophe. For instance:
1375 @smallexample @c projectfile
1378 Var1 := Imported.Var;
1382 @item The second approach is to define the switches in a third project.
1383 That project is setup without any sources (so that, as opposed to
1384 the first example, none of the project plays a special role), and
1385 will only be used to define the attributes. Such a project is
1386 typically called @file{shared.gpr}.
1388 @smallexample @c projectfile
1389 abstract project Shared is
1390 for Source_Files use (); -- no project
1392 for Switches ("Ada") use ("-O2");
1398 package Compiler renames Shared.Compiler;
1403 package Compiler renames Shared.Compiler;
1408 As for the first example, we could have chosen to set the attributes
1409 one by one rather than to rename a package. The reason we explicitly
1410 indicate that @code{Shared} has no sources is so that it can be created
1411 in any directory and we are sure it shares no sources with @code{Build}
1412 or @code{Logging}, which of course would be invalid.
1414 @cindex project qualifier
1415 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1416 This qualifier is optional, but helps convey the message that we do not
1417 intend this project to have sources (@pxref{Qualified Projects} for
1421 @c ---------------------------------------------
1422 @node Global Attributes
1423 @subsection Global Attributes
1424 @c ---------------------------------------------
1427 We have already seen many examples of attributes used to specify a special
1428 option of one of the tools involved in the build process. Most of those
1429 attributes are project specific. That it to say, they only affect the invocation
1430 of tools on the sources of the project where they are defined.
1432 There are a few additional attributes that apply to all projects in a
1433 hierarchy as long as they are defined on the "main" project.
1434 The main project is the project explicitly mentioned on the command-line.
1435 The project hierarchy is the "with"-closure of the main project.
1437 Here is a list of commonly used global attributes:
1440 @item @b{Builder.Global_Configuration_Pragmas}:
1441 @cindex @code{Global_Configuration_Pragmas}
1442 This attribute points to a file that contains configuration pragmas
1443 to use when building executables. These pragmas apply for all
1444 executables built from this project hierarchy. As we have seen before,
1445 additional pragmas can be specified on a per-project basis by setting the
1446 @code{Compiler.Local_Configuration_Pragmas} attribute.
1448 @item @b{Builder.Global_Compilation_Switches}:
1449 @cindex @code{Global_Compilation_Switches}
1450 This attribute is a list of compiler switches to use when compiling any
1451 source file in the project hierarchy. These switches are used in addition
1452 to the ones defined in the @code{Compiler} package, which only apply to
1453 the sources of the corresponding project. This attribute is indexed on
1454 the name of the language.
1458 Using such global capabilities is convenient. It can also lead to unexpected
1459 behavior. Especially when several subsystems are shared among different main
1460 projects and the different global attributes are not
1461 compatible. Note that using aggregate projects can be a safer and more powerful
1462 replacement to global attributes.
1464 @c ---------------------------------------------
1465 @node Scenarios in Projects
1466 @section Scenarios in Projects
1467 @c ---------------------------------------------
1470 Various aspects of the projects can be modified based on @b{scenarios}. These
1471 are user-defined modes that change the behavior of a project. Typical
1472 examples are the setup of platform-specific compiler options, or the use of
1473 a debug and a release mode (the former would activate the generation of debug
1474 information, when the second will focus on improving code optimization).
1476 Let's enhance our example to support a debug and a release modes.The issue is to
1477 let the user choose what kind of system he is building:
1478 use @option{-g} as compiler switches in debug mode and @option{-O2}
1479 in release mode. We will also setup the projects so that we do not share the
1480 same object directory in both modes, otherwise switching from one to the other
1481 might trigger more recompilations than needed or mix objects from the 2 modes.
1483 One naive approach is to create two different project files, say
1484 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1485 attributes as explained in previous sections. This solution does not scale well,
1486 because in presence of multiple projects depending on each other,
1487 you will also have to duplicate the complete hierarchy and adapt the project
1488 files to point to the right copies.
1491 Instead, project files support the notion of scenarios controlled
1492 by external values. Such values can come from several sources (in decreasing
1496 @item @b{Command line}:
1498 When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1499 extra @option{-X} switches to define the external value. In
1500 our case, the command line might look like
1503 gnatmake -Pbuild.gpr -Xmode=debug
1504 or gnatmake -Pbuild.gpr -Xmode=release
1507 @item @b{^Environment variables^Logical names^}:
1508 When the external value does not come from the command line, it can come from
1509 the value of ^environment variables^logical names^ of the appropriate name.
1510 In our case, if ^an environment variable^a logical name^ called "mode"
1511 exist, its value will be taken into account.
1513 @item @b{External function second parameter}
1517 @cindex @code{external}
1518 We now need to get that value in the project. The general form is to use
1519 the predefined function @b{external} which returns the current value of
1520 the external. For instance, we could setup the object directory to point to
1521 either @file{obj/debug} or @file{obj/release} by changing our project to
1523 @smallexample @c projectfile
1525 for Object_Dir use "obj/" & external ("mode", "debug");
1531 The second parameter to @code{external} is optional, and is the default
1532 value to use if "mode" is not set from the command line or the environment.
1534 In order to set the switches according to the different scenarios, other
1535 constructs have to be introduced such as typed variables and case statements.
1537 @cindex typed variable
1538 @cindex case statement
1539 A @b{typed variable} is a variable that
1540 can take only a limited number of values, similar to an enumeration in Ada.
1541 Such a variable can then be used in a @b{case statement} and create conditional
1542 sections in the project. The following example shows how this can be done:
1544 @smallexample @c projectfile
1546 type Mode_Type is ("debug", "release"); -- all possible values
1547 Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1552 for Switches ("Ada") use ("-g");
1554 for Switches ("Ada") use ("-O2");
1561 The project has suddenly grown in size, but has become much more flexible.
1562 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1563 any other value is read from the environment, an error is reported and the
1564 project is considered as invalid.
1566 The @code{Mode} variable is initialized with an external value
1567 defaulting to @code{"debug"}. This default could be omitted and that would
1568 force the user to define the value. Finally, we can use a case statement to set the
1569 switches depending on the scenario the user has chosen.
1571 Most aspects of the projects can depend on scenarios. The notable exception
1572 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1574 Scenarios work the same way with @b{project hierarchies}: you can either
1575 duplicate a variable similar to @code{Mode} in each of the project (as long
1576 as the first argument to @code{external} is always the same and the type is
1577 the same), or simply set the variable in the @file{shared.gpr} project
1578 (@pxref{Sharing Between Projects}).
1580 @c ---------------------------------------------
1581 @node Library Projects
1582 @section Library Projects
1583 @c ---------------------------------------------
1586 So far, we have seen examples of projects that create executables. However,
1587 it is also possible to create libraries instead. A @b{library} is a specific
1588 type of subsystem where, for convenience, objects are grouped together
1589 using system-specific means such as archives or windows DLLs.
1591 Library projects provide a system- and language-independent way of building both @b{static}
1592 and @b{dynamic} libraries. They also support the concept of @b{standalone
1593 libraries} (SAL) which offers two significant properties: the elaboration
1594 (e.g. initialization) of the library is either automatic or very simple;
1596 implementation part of the library implies minimal post-compilation actions on
1597 the complete system and potentially no action at all for the rest of the
1598 system in the case of dynamic SALs.
1600 The GNAT Project Manager takes complete care of the library build, rebuild and
1601 installation tasks, including recompilation of the source files for which
1602 objects do not exist or are not up to date, assembly of the library archive, and
1603 installation of the library (i.e., copying associated source, object and
1604 @file{ALI} files to the specified location).
1607 * Building Libraries::
1608 * Using Library Projects::
1609 * Stand-alone Library Projects::
1610 * Installing a library with project files::
1613 @c ---------------------------------------------
1614 @node Building Libraries
1615 @subsection Building Libraries
1616 @c ---------------------------------------------
1619 Let's enhance our example and transform the @code{logging} subsystem into a
1620 library. In order to do so, a few changes need to be made to @file{logging.gpr}.
1621 A number of specific attributes needs to be defined: at least @code{Library_Name}
1622 and @code{Library_Dir}; in addition, a number of other attributes can be used
1623 to specify specific aspects of the library. For readability, it is also
1624 recommended (although not mandatory), to use the qualifier @code{library} in
1625 front of the @code{project} keyword.
1628 @item @b{Library_Name}:
1629 @cindex @code{Library_Name}
1630 This attribute is the name of the library to be built. There is no
1631 restriction on the name of a library imposed by the project manager, except
1632 for stand-alone libraries whose names must follow the syntax of Ada
1633 identifiers; however, there may be system specific restrictions on the name.
1634 In general, it is recommended to stick to alphanumeric characters (and
1635 possibly single underscores) to help portability.
1637 @item @b{Library_Dir}:
1638 @cindex @code{Library_Dir}
1639 This attribute is the path (absolute or relative) of the directory where
1640 the library is to be installed. In the process of building a library,
1641 the sources are compiled, the object files end up in the explicit or
1642 implicit @code{Object_Dir} directory. When all sources of a library
1643 are compiled, some of the compilation artifacts, including the library itself,
1644 are copied to the library_dir directory. This directory must exists and be
1645 writable. It must also be different from the object directory so that cleanup
1646 activities in the Library_Dir do not affect recompilation needs.
1650 Here is the new version of @file{logging.gpr} that makes it a library:
1652 @smallexample @c projectfile
1653 library project Logging is -- "library" is optional
1654 for Library_Name use "logging"; -- will create "liblogging.a" on Unix
1655 for Object_Dir use "obj";
1656 for Library_Dir use "lib"; -- different from object_dir
1661 Once the above two attributes are defined, the library project is valid and
1662 is enough for building a library with default characteristics.
1663 Other library-related attributes can be used to change the defaults:
1666 @item @b{Library_Kind}:
1667 @cindex @code{Library_Kind}
1668 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1669 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1670 which kind of library should be built (the default is to build a
1671 static library, that is an archive of object files that can potentially
1672 be linked into a static executable). When the library is set to be dynamic,
1673 a separate image is created that will be loaded independently, usually
1674 at the start of the main program execution. Support for dynamic libraries is
1675 very platform specific, for instance on Windows it takes the form of a DLL
1676 while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1677 @file{.so}. Library project files, on the other hand, can be written in
1678 a platform independent way so that the same project file can be used to build
1679 a library on different operating systems.
1681 If you need to build both a static and a dynamic library, it is recommended
1682 use two different object directories, since in some cases some extra code
1683 needs to be generated for the latter. For such cases, one can
1684 either define two different project files, or a single one which uses scenarios
1685 to indicate the various kinds of library to be built and their
1686 corresponding object_dir.
1688 @cindex @code{Library_ALI_Dir}
1689 @item @b{Library_ALI_Dir}:
1690 This attribute may be specified to indicate the directory where the ALI
1691 files of the library are installed. By default, they are copied into the
1692 @code{Library_Dir} directory, but as for the executables where we have a
1693 separate @code{Exec_Dir} attribute, you might want to put them in a separate
1694 directory since there can be hundreds of them. The same restrictions as for
1695 the @code{Library_Dir} attribute apply.
1697 @cindex @code{Library_Version}
1698 @item @b{Library_Version}:
1699 This attribute is platform dependent, and has no effect on VMS and Windows.
1700 On Unix, it is used only for dynamic libraries as the internal
1701 name of the library (the @code{"soname"}). If the library file name (built
1702 from the @code{Library_Name}) is different from the @code{Library_Version},
1703 then the library file will be a symbolic link to the actual file whose name
1704 will be @code{Library_Version}. This follows the usual installation schemes
1705 for dynamic libraries on many Unix systems.
1707 @smallexample @c projectfile
1711 for Library_Dir use "lib";
1712 for Library_Name use "logging";
1713 for Library_Kind use "dynamic";
1714 for Library_Version use "liblogging.so." & Version;
1720 After the compilation, the directory @file{lib} will contain both a
1721 @file{libdummy.so.1} library and a symbolic link to it called
1724 @cindex @code{Library_GCC}
1725 @item @b{Library_GCC}:
1726 This attribute is the name of the tool to use instead of "gcc" to link shared
1727 libraries. A common use of this attribute is to define a wrapper script that
1728 accomplishes specific actions before calling gcc (which itself is calling the
1729 linker to build the library image).
1731 @item @b{Library_Options}:
1732 @cindex @code{Library_Options}
1733 This attribute may be used to specify additional switches (last switches)
1734 when linking a shared library.
1736 @item @b{Leading_Library_Options}:
1737 @cindex @code{Leading_Library_Options}
1738 This attribute, that is taken into account only by @command{gprbuild}, may be
1739 used to specified leading options (first switches) when linking a shared
1742 @cindex @code{Linker_Options}
1743 @item @b{Linker.Linker_Options}:
1744 This attribute specifies additional switches to be given to the linker when
1745 linking an executable. It is ignored when defined in the main project and
1746 taken into account in all other projects that are imported directly or
1747 indirectly. These switches complement the @code{Linker.Switches}
1748 defined in the main project. This is useful when a particular subsystem
1749 depends on an external library: adding this dependency as a
1750 @code{Linker_Options} in the project of the subsystem is more convenient than
1751 adding it to all the @code{Linker.Switches} of the main projects that depend
1752 upon this subsystem.
1755 @c ---------------------------------------------
1756 @node Using Library Projects
1757 @subsection Using Library Projects
1758 @c ---------------------------------------------
1761 When the builder detects that a project file is a library project file, it
1762 recompiles all sources of the project that need recompilation and rebuild the
1763 library if any of the sources have been recompiled. It then groups all object
1764 files into a single file, which is a shared or a static library. This library
1765 can later on be linked with multiple executables. Note that the use
1766 of shard libraries reduces the size of the final executable and can also reduce
1767 the memory footprint at execution time when the library is shared among several
1770 It is also possible to build @b{multi-language libraries}. When using
1771 @command{gprbuild} as a builder, multi-language library projects allow naturally
1772 the creation of multi-language libraries . @command{gnatmake}, does not try to
1773 compile non Ada sources. However, when the project is multi-language, it will
1774 automatically link all object files found in the object directory, whether or
1775 not they were compiled from an Ada source file. This specific behavior does not
1776 apply to Ada-only projects which only take into account the objects
1777 corresponding to the sources of the project.
1779 A non-library project can import a library project. When the builder is invoked
1780 on the former, the library of the latter is only rebuilt when absolutely
1781 necessary. For instance, if a unit of the
1782 library is not up-to-date but non of the executables need this unit, then the
1783 unit is not recompiled and the library is not reassembled.
1784 For instance, let's assume in our example that logging has the following
1785 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1786 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1787 @file{liblogging} will be rebuilt when compiling all the sources of
1788 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1789 include a @code{"with Log1"}.
1791 To ensure that all the sources in the @code{Logging} library are
1792 up to date, and that all the sources of @code{Build} are also up to date,
1793 the following two commands needs to be used:
1796 gnatmake -Plogging.gpr
1797 gnatmake -Pbuild.gpr
1801 All @file{ALI} files will also be copied from the object directory to the
1802 library directory. To build executables, @command{gnatmake} will use the
1803 library rather than the individual object files.
1806 Library projects can also be useful to describe a library that need to be used
1807 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1808 of the library sources are not available. Such library projects need simply to
1809 use the @code{Externally_Built} attribute as in the example below:
1811 @smallexample @c projectfile
1812 library project Extern_Lib is
1813 for Languages use ("Ada", "C");
1814 for Source_Dirs use ("lib_src");
1815 for Library_Dir use "lib2";
1816 for Library_Kind use "dynamic";
1817 for Library_Name use "l2";
1818 for Externally_Built use "true"; -- <<<<
1823 In the case of externally built libraries, the @code{Object_Dir}
1824 attribute does not need to be specified because it will never be
1827 The main effect of using such an externally built library project is mostly to
1828 affect the linker command in order to reference the desired library. It can
1829 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1830 in the project corresponding to the subsystem needing this external library.
1831 This latter method is more straightforward in simple cases but when several
1832 subsystems depend upon the same external library, finding the proper place
1833 for the @code{Linker.Linker_Options} might not be easy and if it is
1834 not placed properly, the final link command is likely to present ordering issues.
1835 In such a situation, it is better to use the externally built library project
1836 so that all other subsystems depending on it can declare this dependency thanks
1837 to a project @code{with} clause, which in turn will trigger the builder to find
1838 the proper order of libraries in the final link command.
1841 @c ---------------------------------------------
1842 @node Stand-alone Library Projects
1843 @subsection Stand-alone Library Projects
1844 @c ---------------------------------------------
1847 @cindex standalone libraries
1848 A @b{stand-alone library} is a library that contains the necessary code to
1849 elaborate the Ada units that are included in the library. A stand-alone
1850 library is a convenient way to add an Ada subsystem to a more global system
1851 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1852 transparent. However, stand-alone libraries are also useful when the main is in
1853 Ada: they provide a means for minimizing relinking & redeployment of complex
1854 systems when localized changes are made.
1856 The name of a stand-alone library, specified with attribute
1857 @code{Library_Name}, must have the syntax of an Ada identifier.
1859 The most prominent characteristic of a stand-alone library is that it offers a
1860 distinction between interface units and implementation units. Only the former
1861 are visible to units outside the library. A stand-alone library project is thus
1862 characterised by a third attribute, usually @b{Library_Interface}, in addition
1863 to the two attributes that make a project a Library Project
1864 (@code{Library_Name} and @code{Library_Dir}). This third attribute may also be
1865 @b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada
1866 and takes a list of units as parameter. @b{Interfaces} works for any supported
1867 language and takes a list of sources as parameter.
1870 @item @b{Library_Interface}:
1871 @cindex @code{Library_Interface}
1872 This attribute defines an explicit subset of the units of the project. Units
1873 from projects importing this library project may only "with" units whose
1874 sources are listed in the @code{Library_Interface}. Other sources are
1875 considered implementation units.
1877 @smallexample @c projectfile
1879 for Library_Dir use "lib";
1880 for Library_Name use "loggin";
1881 for Library_Interface use ("lib1", "lib2"); -- unit names
1885 @item @b{Interfaces}
1886 This attribute defines an explicit subset of the source files of a project.
1887 Sources from projects importing this project, can only depend on sources from
1888 this subset. This attribute can be used on non library projects. It can also
1889 be used as a replacement for attribute @code{Library_Interface}, in which
1890 case, units have to be replaced by source files. For multi-language library
1891 projects, it is the only way to make the project a Stand-Alone Library project
1892 whose interface is not purely Ada.
1894 @item @b{Library_Standalone}:
1895 @cindex @code{Library_Standalone}
1896 This attribute defines the kind of standalone library to
1897 build. Values are either @code{standard} (the default), @code{no} or
1898 @code{encapsulated}. When @code{standard} is used the code to elaborate and
1899 finalize the library is embedded, when @code{encapsulated} is used the
1900 library can furthermore only depends on static libraries (including
1901 the GNAT runtime). This attribute can be set to @code{no} to make it clear
1902 that the library should not be standalone in which case the
1903 @code{Library_Interface} should not defined.
1905 @smallexample @c projectfile
1907 for Library_Dir use "lib";
1908 for Library_Name use "loggin";
1909 for Library_Interface use ("lib1", "lib2"); -- unit names
1910 for Library_Standalone use "encapsulated";
1916 In order to include the elaboration code in the stand-alone library, the binder
1917 is invoked on the closure of the library units creating a package whose name
1918 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1919 This binder-generated package includes @b{initialization} and @b{finalization}
1920 procedures whose names depend on the library name (@code{logginginit} and
1921 @code{loggingfinal} in the example). The object corresponding to this package is
1922 included in the library.
1925 @item @b{Library_Auto_Init}:
1926 @cindex @code{Library_Auto_Init}
1927 A dynamic stand-alone Library is automatically initialized
1928 if automatic initialization of Stand-alone Libraries is supported on the
1929 platform and if attribute @b{Library_Auto_Init} is not specified or
1930 is specified with the value "true". A static Stand-alone Library is never
1931 automatically initialized. Specifying "false" for this attribute
1932 prevent automatic initialization.
1934 When a non-automatically initialized stand-alone library is used in an
1935 executable, its initialization procedure must be called before any service of
1936 the library is used. When the main subprogram is in Ada, it may mean that the
1937 initialization procedure has to be called during elaboration of another
1940 @item @b{Library_Dir}:
1941 @cindex @code{Library_Dir}
1942 For a stand-alone library, only the @file{ALI} files of the interface units
1943 (those that are listed in attribute @code{Library_Interface}) are copied to
1944 the library directory. As a consequence, only the interface units may be
1945 imported from Ada units outside of the library. If other units are imported,
1946 the binding phase will fail.
1948 @item @b{Binder.Default_Switches}:
1949 When a stand-alone library is bound, the switches that are specified in
1950 the attribute @b{Binder.Default_Switches ("Ada")} are
1951 used in the call to @command{gnatbind}.
1953 @item @b{Library_Src_Dir}:
1954 @cindex @code{Library_Src_Dir}
1955 This attribute defines the location (absolute or relative to the project
1956 directory) where the sources of the interface units are copied at
1958 These sources includes the specs of the interface units along with the closure
1959 of sources necessary to compile them successfully. That may include bodies and
1960 subunits, when pragmas @code{Inline} are used, or when there is a generic
1961 units in the spec. This directory cannot point to the object directory or
1962 one of the source directories, but it can point to the library directory,
1963 which is the default value for this attribute.
1965 @item @b{Library_Symbol_Policy}:
1966 @cindex @code{Library_Symbol_Policy}
1967 This attribute controls the export of symbols and, on some platforms (like
1968 VMS) that have the notions of major and minor IDs built in the library
1969 files, it controls the setting of these IDs. It is not supported on all
1970 platforms (where it will just have no effect). It may have one of the
1974 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1975 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1976 is not defined, then it is equivalent to policy "autonomous". If there
1977 are exported symbols in the reference symbol file that are not in the
1978 object files of the interfaces, the major ID of the library is increased.
1979 If there are symbols in the object files of the interfaces that are not
1980 in the reference symbol file, these symbols are put at the end of the list
1981 in the newly created symbol file and the minor ID is increased.
1982 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1983 defined. The library will fail to build if the exported symbols in the
1984 object files of the interfaces do not match exactly the symbol in the
1986 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1987 The library will fail to build if there are symbols in the symbol file that
1988 are not in the exported symbols of the object files of the interfaces.
1989 Additional symbols in the object files are not added to the symbol file.
1990 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1991 must designate an existing file in the object directory. This symbol file
1992 is passed directly to the underlying linker without any symbol processing.
1996 @item @b{Library_Reference_Symbol_File}
1997 @cindex @code{Library_Reference_Symbol_File}
1998 This attribute may define the path name of a reference symbol file that is
1999 read when the symbol policy is either "compliant" or "controlled", on
2000 platforms that support symbol control, such as VMS, when building a
2001 stand-alone library. The path may be an absolute path or a path relative
2002 to the project directory.
2004 @item @b{Library_Symbol_File}
2005 @cindex @code{Library_Symbol_File}
2006 This attribute may define the name of the symbol file to be created when
2007 building a stand-alone library when the symbol policy is either "compliant",
2008 "controlled" or "restricted", on platforms that support symbol control,
2009 such as VMS. When symbol policy is "direct", then a file with this name
2010 must exist in the object directory.
2013 @c ---------------------------------------------
2014 @node Installing a library with project files
2015 @subsection Installing a library with project files
2016 @c ---------------------------------------------
2019 When using project files, a usable version of the library is created in the
2020 directory specified by the @code{Library_Dir} attribute of the library
2021 project file. Thus no further action is needed in order to make use of
2022 the libraries that are built as part of the general application build.
2024 You may want to install a library in a context different from where the library
2025 is built. This situation arises with third party suppliers, who may want
2026 to distribute a library in binary form where the user is not expected to be
2027 able to recompile the library. The simplest option in this case is to provide
2028 a project file slightly different from the one used to build the library, by
2029 using the @code{externally_built} attribute. @ref{Using Library Projects}
2031 Another option is to use @command{gprinstall} to install the library in a
2032 different context than the build location. A project to use this library is
2033 generated automatically by @command{gprinstall} which also copy, in the install
2034 location, the minimum set of sources needed to use the library.
2037 @c ---------------------------------------------
2038 @node Project Extension
2039 @section Project Extension
2040 @c ---------------------------------------------
2043 During development of a large system, it is sometimes necessary to use
2044 modified versions of some of the source files, without changing the original
2045 sources. This can be achieved through the @b{project extension} facility.
2047 Suppose for instance that our example @code{Build} project is built every night
2048 for the whole team, in some shared directory. A developer usually need to work
2049 on a small part of the system, and might not want to have a copy of all the
2050 sources and all the object files (mostly because that would require too much
2051 disk space, time to recompile everything). He prefers to be able to override
2052 some of the source files in his directory, while taking advantage of all the
2053 object files generated at night.
2055 Another example can be taken from large software systems, where it is common to have
2056 multiple implementations of a common interface; in Ada terms, multiple
2057 versions of a package body for the same spec. For example, one implementation
2058 might be safe for use in tasking programs, while another might only be used
2059 in sequential applications. This can be modeled in GNAT using the concept
2060 of @emph{project extension}. If one project (the ``child'') @emph{extends}
2061 another project (the ``parent'') then by default all source files of the
2062 parent project are inherited by the child, but the child project can
2063 override any of the parent's source files with new versions, and can also
2064 add new files or remove unnecessary ones.
2065 This facility is the project analog of a type extension in
2066 object-oriented programming. Project hierarchies are permitted (an extending
2067 project may itself be extended), and a project that
2068 extends a project can also import other projects.
2070 A third example is that of using project extensions to provide different
2071 versions of the same system. For instance, assume that a @code{Common}
2072 project is used by two development branches. One of the branches has now
2073 been frozen, and no further change can be done to it or to @code{Common}.
2074 However, the other development branch still needs evolution of @code{Common}.
2075 Project extensions provide a flexible solution to create a new version
2076 of a subsystem while sharing and reusing as much as possible from the original
2079 A project extension inherits implicitly all the sources and objects from the
2080 project it extends. It is possible to create a new version of some of the
2081 sources in one of the additional source dirs of the extending project. Those new
2082 versions hide the original versions. Adding new sources or removing existing
2083 ones is also possible. Here is an example on how to extend the project
2084 @code{Build} from previous examples:
2086 @smallexample @c projectfile
2087 project Work extends "../bld/build.gpr" is
2092 The project after @b{extends} is the one being extended. As usual, it can be
2093 specified using an absolute path, or a path relative to any of the directories
2094 in the project path (@pxref{Project Dependencies}). This project does not
2095 specify source or object directories, so the default value for these attribute
2096 will be used that is to say the current directory (where project @code{Work} is
2097 placed). We can already compile that project with
2104 If no sources have been placed in the current directory, this command
2105 won't do anything, since this project does not change the
2106 sources it inherited from @code{Build}, therefore all the object files
2107 in @code{Build} and its dependencies are still valid and are reused
2110 Suppose we now want to supply an alternate version of @file{pack.adb}
2111 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
2112 We can create the new file Work's current directory (likely
2113 by copying the one from the @code{Build} project and making changes to
2114 it. If new packages are needed at the same time, we simply create
2115 new files in the source directory of the extending project.
2117 When we recompile, @command{gnatmake} will now automatically recompile
2118 this file (thus creating @file{pack.o} in the current directory) and
2119 any file that depends on it (thus creating @file{proc.o}). Finally, the
2120 executable is also linked locally.
2122 Note that we could have obtained the desired behavior using project import
2123 rather than project inheritance. A @code{base} project would contain the
2124 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
2125 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
2126 cannot contain the original version of @file{pack.adb} otherwise there would be
2127 2 versions of the same unit in the closure of the project and this is not
2128 allowed. Generally speaking, it is not recommended to put the spec and the
2129 body of a unit in different projects since this affects their autonomy and
2132 In a project file that extends another project, it is possible to
2133 indicate that an inherited source is @b{not part} of the sources of the
2134 extending project. This is necessary sometimes when a package spec has
2135 been overridden and no longer requires a body: in this case, it is
2136 necessary to indicate that the inherited body is not part of the sources
2137 of the project, otherwise there will be a compilation error
2138 when compiling the spec.
2140 @cindex @code{Excluded_Source_Files}
2141 @cindex @code{Excluded_Source_List_File}
2142 For that purpose, the attribute @b{Excluded_Source_Files} is used.
2143 Its value is a list of file names.
2144 It is also possible to use attribute @code{Excluded_Source_List_File}.
2145 Its value is the path of a text file containing one file name per
2148 @smallexample @c @projectfile
2149 project Work extends "../bld/build.gpr" is
2150 for Source_Files use ("pack.ads");
2151 -- New spec of Pkg does not need a completion
2152 for Excluded_Source_Files use ("pack.adb");
2157 All packages that are not declared in the extending project are inherited from
2158 the project being extended, with their attributes, with the exception of
2159 @code{Linker'Linker_Options} which is never inherited. In particular, an
2160 extending project retains all the switches specified in the project being
2163 At the project level, if they are not declared in the extending project, some
2164 attributes are inherited from the project being extended. They are:
2165 @code{Languages}, @code{Main} (for a root non library project) and
2166 @code{Library_Name} (for a project extending a library project)
2169 * Project Hierarchy Extension::
2172 @c ---------------------------------------------
2173 @node Project Hierarchy Extension
2174 @subsection Project Hierarchy Extension
2175 @c ---------------------------------------------
2178 One of the fundamental restrictions in project extension is the following:
2179 @b{A project is not allowed to import directly or indirectly at the same time an
2180 extending project and one of its ancestors}.
2182 By means of example, consider the following hierarchy of projects.
2185 a.gpr contains package A1
2186 b.gpr, imports a.gpr and contains B1, which depends on A1
2187 c.gpr, imports b.gpr and contains C1, which depends on B1
2191 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2192 create several extending projects:
2195 a_ext.gpr which extends a.gpr, and overrides A1
2196 b_ext.gpr which extends b.gpr and imports a_ext.gpr
2197 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2201 @smallexample @c projectfile
2202 project A_Ext extends "a.gpr" is
2203 for Source_Files use ("a1.adb", "a1.ads");
2207 project B_Ext extends "b.gpr" is
2211 project C_Ext extends "c.gpr" is
2212 for Source_Files use ("c1.adb");
2217 The extension @file{b_ext.gpr} is required, even though we are not overriding
2218 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2219 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2222 When extending a large system spanning multiple projects, it is often
2223 inconvenient to extend every project in the hierarchy that is impacted by a
2224 small change introduced in a low layer. In such cases, it is possible to create
2225 an @b{implicit extension} of entire hierarchy using @b{extends all}
2228 When the project is extended using @code{extends all} inheritance, all projects
2229 that are imported by it, both directly and indirectly, are considered virtually
2230 extended. That is, the project manager creates implicit projects
2231 that extend every project in the hierarchy; all these implicit projects do not
2232 control sources on their own and use the object directory of
2233 the "extending all" project.
2235 It is possible to explicitly extend one or more projects in the hierarchy
2236 in order to modify the sources. These extending projects must be imported by
2237 the "extending all" project, which will replace the corresponding virtual
2238 projects with the explicit ones.
2240 When building such a project hierarchy extension, the project manager will
2241 ensure that both modified sources and sources in implicit extending projects
2242 that depend on them, are recompiled.
2244 Thus, in our example we could create the following projects instead:
2247 a_ext.gpr, extends a.gpr and overrides A1
2248 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2253 @smallexample @c projectfile
2254 project A_Ext extends "a.gpr" is
2255 for Source_Files use ("a1.adb", "a1.ads");
2259 project C_Ext extends all "c.gpr" is
2260 for Source_Files use ("c1.adb");
2265 When building project @file{c_ext.gpr}, the entire modified project space is
2266 considered for recompilation, including the sources of @file{b.gpr} that are
2267 impacted by the changes in @code{A1} and @code{C1}.
2269 @c ---------------------------------------------
2270 @node Aggregate Projects
2271 @section Aggregate Projects
2272 @c ---------------------------------------------
2276 Aggregate projects are an extension of the project paradigm, and are
2277 meant to solve a few specific use cases that cannot be solved directly
2278 using standard projects. This section will go over a few of these use
2279 cases to try to explain what you can use aggregate projects for.
2282 * Building all main programs from a single project tree::
2283 * Building a set of projects with a single command::
2284 * Define a build environment::
2285 * Performance improvements in builder::
2286 * Syntax of aggregate projects::
2287 * package Builder in aggregate projects::
2290 @c -----------------------------------------------------------
2291 @node Building all main programs from a single project tree
2292 @subsection Building all main programs from a single project tree
2293 @c -----------------------------------------------------------
2295 Most often, an application is organized into modules and submodules,
2296 which are very conveniently represented as a project tree or graph
2297 (the root project A @code{with}s the projects for each modules (say B and C),
2298 which in turn @code{with} projects for submodules.
2300 Very often, modules will build their own executables (for testing
2301 purposes for instance), or libraries (for easier reuse in various
2304 However, if you build your project through @command{gnatmake} or
2305 @command{gprbuild}, using a syntax similar to
2311 this will only rebuild the main programs of project A, not those of the
2312 imported projects B and C. Therefore you have to spawn several
2313 @command{gnatmake} commands, one per project, to build all executables.
2314 This is a little inconvenient, but more importantly is inefficient
2315 because @command{gnatmake} needs to do duplicate work to ensure that sources are
2316 up-to-date, and cannot easily compile things in parallel when using
2319 Also libraries are always rebuilt when building a project.
2321 You could therefore define an aggregate project Agg that groups A, B
2322 and C. Then, when you build with
2328 this will build all mains from A, B and C.
2330 @smallexample @c projectfile
2331 aggregate project Agg is
2332 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2336 If B or C do not define any main program (through their Main
2337 attribute), all their sources are built. When you do not group them
2338 in the aggregate project, only those sources that are needed by A
2341 If you add a main to a project P not already explicitly referenced in the
2342 aggregate project, you will need to add "p.gpr" in the list of project
2343 files for the aggregate project, or the main will not be built when
2344 building the aggregate project.
2346 @c ---------------------------------------------------------
2347 @node Building a set of projects with a single command
2348 @subsection Building a set of projects with a single command
2349 @c ---------------------------------------------------------
2351 One other case is when you have multiple applications and libraries
2352 that are built independently from each other (but can be built in
2353 parallel). For instance, you have a project tree rooted at A, and
2354 another one (which might share some subprojects) rooted at B.
2356 Using only @command{gprbuild}, you could do
2363 to build both. But again, @command{gprbuild} has to do some duplicate work for
2364 those files that are shared between the two, and cannot truly build
2365 things in parallel efficiently.
2367 If the two projects are really independent, share no sources other
2368 than through a common subproject, and have no source files with a
2369 common basename, you could create a project C that imports A and
2370 B. But these restrictions are often too strong, and one has to build
2371 them independently. An aggregate project does not have these
2372 limitations and can aggregate two project trees that have common
2375 This scenario is particularly useful in environments like VxWorks 653
2376 where the applications running in the multiple partitions can be built
2377 in parallel through a single @command{gprbuild} command. This also works nicely
2380 @c ---------------------------------------------
2381 @node Define a build environment
2382 @subsection Define a build environment
2383 @c ---------------------------------------------
2385 The environment variables at the time you launch @command{gprbuild} or
2386 @command{gnatmake} will influence the view these tools have of the project
2387 (PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
2388 projects, environment variables that are referenced in project files
2389 through the "external" statement,...). Several command line switches
2390 can be used to override those (-X or -aP), but on some systems and
2391 with some projects, this might make the command line too long, and on
2392 all systems often make it hard to read.
2394 An aggregate project can be used to set the environment for all
2395 projects built through that aggregate. One of the nice aspects is that
2396 you can put the aggregate project under configuration management, and
2397 make sure all your user have a consistent environment when
2398 building. The syntax looks like
2400 @smallexample @c projectfile
2401 aggregate project Agg is
2402 for Project_Files use ("A.gpr", "B.gpr");
2403 for Project_Path use ("../dir1", "../dir1/dir2");
2404 for External ("BUILD") use "PRODUCTION";
2407 for Switches ("Ada") use ("-q");
2412 One of the often requested features in projects is to be able to
2413 reference external variables in @code{with} statements, as in
2415 @smallexample @c projectfile
2416 with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
2417 project MyProject is
2422 For various reasons, this isn't authorized. But using aggregate
2423 projects provide an elegant solution. For instance, you could
2424 use a project file like:
2426 @smallexample @c projectfile
2427 aggregate project Agg is
2428 for Project_Path use (external("SETUP") % "path");
2429 for Project_Files use ("myproject.gpr");
2432 with "prj.gpr"; -- searched on Agg'Project_Path
2433 project MyProject is
2438 @c --------------------------------------------
2439 @node Performance improvements in builder
2440 @subsection Performance improvements in builder
2441 @c --------------------------------------------
2443 The loading of aggregate projects is optimized in @command{gprbuild} and
2444 @command{gnatmake}, so that all files are searched for only once on the disk
2445 (thus reducing the number of system calls and contributing to faster
2446 compilation times especially on systems with sources on remote
2447 servers). As part of the loading, @command{gprbuild} and @command{gnatmake}
2448 compute how and where a source file should be compiled, and even if it is found
2449 several times in the aggregated projects it will be compiled only
2452 Since there is no ambiguity as to which switches should be used, files
2453 can be compiled in parallel (through the usual -j switch) and this can
2454 be done while maximizing the use of CPUs (compared to launching
2455 multiple @command{gprbuild} and @command{gnatmake} commands in parallel).
2457 @c -------------------------------------
2458 @node Syntax of aggregate projects
2459 @subsection Syntax of aggregate projects
2460 @c -------------------------------------
2462 An aggregate project follows the general syntax of project files. The
2463 recommended extension is still @file{.gpr}. However, a special
2464 @code{aggregate} qualifier must be put before the keyword
2467 An aggregate project cannot @code{with} any other project (standard or
2468 aggregate), except an abstract project which can be used to share
2469 attribute values. Building other aggregate projects from an aggregate
2470 project is done through the Project_Files attribute (see below).
2472 An aggregate project does not have any source files directly (only
2473 through other standard projects). Therefore a number of the standard
2474 attributes and packages are forbidden in an aggregate project. Here is the
2475 (non exhaustive) list:
2479 @item Source_Files, Source_List_File and other attributes dealing with
2481 @item Source_Dirs, Exec_Dir and Object_Dir
2482 @item Library_Dir, Library_Name and other library-related attributes
2485 @item Externally_Built
2486 @item Inherit_Source_Path
2487 @item Excluded_Source_Dirs
2488 @item Locally_Removed_Files
2489 @item Excluded_Source_Files
2490 @item Excluded_Source_List_File
2494 The only package that is authorized (albeit optional) is
2495 Builder. Other packages (in particular Compiler, Binder and Linker)
2496 are forbidden. It is an error to have any of these
2497 (and such an error prevents the proper loading of the aggregate
2500 Three new attributes have been created, which can only be used in the
2501 context of aggregate projects:
2504 @item @b{Project_Files}:
2505 @cindex @code{Project_Files}
2507 This attribute is compulsory (or else we are not aggregating any project,
2508 and thus not doing anything). It specifies a list of @file{.gpr} files
2509 that are grouped in the aggregate. The list may be empty. The project
2510 files can be either other aggregate projects, or standard projects. When
2511 grouping standard projects, you can have both the root of a project tree
2512 (and you do not need to specify all its imported projects), and any project
2515 Basically, the idea is to specify all those projects that have
2516 main programs you want to build and link, or libraries you want to
2517 build. You can even specify projects that do not use the Main
2518 attribute nor the @code{Library_*} attributes, and the result will be to
2519 build all their source files (not just the ones needed by other
2522 The file can include paths (absolute or relative). Paths are
2523 relative to the location of the aggregate project file itself (if
2524 you use a base name, we expect to find the .gpr file in the same
2525 directory as the aggregate project file). The extension @file{.gpr} is
2526 mandatory, since this attribute contains file names, not project names.
2528 Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
2529 latter indicates that any subdirectory (recursively) will be
2530 searched for matching files. The latter (@code{"**"}) can only occur at the
2531 last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
2532 not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
2533 to starting with @code{"./**"}.
2535 For now, the pattern @code{"*"} is only allowed in the filename part, not
2536 in the directory part. This is mostly for efficiency reasons to limit the
2537 number of system calls that are needed.
2539 Here are a few valid examples:
2541 @smallexample @c projectfile
2542 for Project_Files use ("a.gpr", "subdir/b.gpr");
2543 -- two specific projects relative to the directory of agg.gpr
2545 for Project_Files use ("**/*.gpr");
2546 -- all projects recursively
2549 @item @b{Project_Path}:
2550 @cindex @code{Project_Path}
2552 This attribute can be used to specify a list of directories in
2553 which to look for project files in @code{with} statements.
2555 When you specify a project in Project_Files
2556 say @code{"x/y/a.gpr"}), and this projects imports a project "b.gpr", only
2557 b.gpr is searched in the project path. a.gpr must be exactly at
2558 <dir of the aggregate>/x/y/a.gpr.
2560 This attribute, however, does not affect the search for the aggregated
2561 project files specified with @code{Project_Files}.
2563 Each aggregate project has its own (that is if agg1.gpr includes
2564 agg2.gpr, they can potentially both have a different project path).
2566 This project path is defined as the concatenation, in that order, of:
2569 @item the current directory;
2570 @item followed by the command line -aP switches;
2571 @item then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment
2573 @item then the directories from the Project_Path attribute;
2574 @item and finally the predefined directories.
2577 In the example above, agg2.gpr's project path is not influenced by
2578 the attribute agg1'Project_Path, nor is agg1 influenced by
2581 This can potentially lead to errors. In the following example:
2584 +---------------+ +----------------+
2585 | Agg1.gpr |-=--includes--=-->| Agg2.gpr |
2586 | 'project_path| | 'project_path |
2588 +---------------+ +----------------+
2593 +-------+ +---------+
2594 | P.gpr |<---------- withs --------| Q.gpr |
2595 +-------+---------\ +---------+
2600 +-------+ +---------+
2601 | R.gpr | | R'.gpr |
2602 +-------+ +---------+
2605 When looking for p.gpr, both aggregates find the same physical file on
2606 the disk. However, it might happen that with their different project
2607 paths, both aggregate projects would in fact find a different r.gpr.
2608 Since we have a common project (p.gpr) "with"ing two different r.gpr,
2609 this will be reported as an error by the builder.
2611 Directories are relative to the location of the aggregate project file.
2613 Here are a few valid examples:
2615 @smallexample @c projectfile
2616 for Project_Path use ("/usr/local/gpr", "gpr/");
2620 @cindex @code{External}
2622 This attribute can be used to set the value of environment
2623 variables as retrieved through the @code{external} statement
2624 in projects. It does not affect the environment variables
2625 themselves (so for instance you cannot use it to change the value
2626 of your PATH as seen from the spawned compiler).
2628 This attribute affects the external values as seen in the rest of
2629 the aggreate projects, and in the aggregated projects.
2631 The exact value of external a variable comes from one of three
2632 sources (each level overrides the previous levels):
2635 @item An External attribute in aggregate project, for instance
2636 @code{for External ("BUILD_MODE") use "DEBUG"};
2638 @item Environment variables
2640 These override the value given by the attribute, so that
2641 users can override the value set in the (presumably shared
2642 with others in his team) aggregate project.
2644 @item The -X command line switch to @command{gprbuild} and @command{gnatmake}
2646 This always takes precedence.
2650 This attribute is only taken into account in the main aggregate
2651 project (i.e. the one specified on the command line to @command{gprbuild} or
2652 @command{gnatmake}), and ignored in other aggregate projects. It is invalid
2653 in standard projects.
2654 The goal is to have a consistent value in all
2655 projects that are built through the aggregate, which would not
2656 be the case in the diamond case: A groups the aggregate
2657 projects B and C, which both (either directly or indirectly)
2658 build the project P. If B and C could set different values for
2659 the environment variables, we would have two different views of
2660 P, which in particular might impact the list of source files in P.
2664 @c ----------------------------------------------
2665 @node package Builder in aggregate projects
2666 @subsection package Builder in aggregate projects
2667 @c ----------------------------------------------
2669 As we mentioned before, only the package Builder can be specified in
2670 an aggregate project. In this package, only the following attributes
2675 @cindex @code{Switches}
2676 This attribute gives the list of switches to use for the builder
2677 (@command{gprbuild} or @command{gnatmake}), depending on the language of the
2678 main file. For instance,
2680 @smallexample @c projectfile
2681 for Switches ("Ada") use ("-d", "-p");
2682 for Switches ("C") use ("-p");
2685 These switches are only read from the main aggregate project (the
2686 one passed on the command line), and ignored in all other aggregate
2687 projects or projects.
2689 It can only contain builder switches, not compiler switches.
2691 @item @b{Global_Compilation_Switches}
2692 @cindex @code{Global_Compilation_Switches}
2694 This attribute gives the list of compiler switches for the various
2695 languages. For instance,
2697 @smallexample @c projectfile
2698 for Global_Compilation_Switches ("Ada") use ("-O1", "-g");
2699 for Global_Compilation_Switches ("C") use ("-O2");
2702 This attribute is only taken into account in the aggregate project
2703 specified on the command line, not in other aggregate projects.
2705 In the projects grouped by that aggregate, the attribute
2706 Builder.Global_Compilation_Switches is also ignored. However, the
2707 attribute Compiler.Default_Switches will be taken into account (but
2708 that of the aggregate have higher priority). The attribute
2709 Compiler.Switches is also taken into account and can be used to
2710 override the switches for a specific file. As a result, it always
2713 The rules are meant to avoid ambiguities when compiling. For
2714 instance, aggregate project Agg groups the projects A and B, that
2715 both depend on C. Here is an extra for all of these projects:
2717 @smallexample @c projectfile
2718 aggregate project Agg is
2719 for Project_Files use ("a.gpr", "b.gpr");
2721 for Global_Compilation_Switches ("Ada") use ("-O2");
2728 for Global_Compilation_Switches ("Ada") use ("-O1");
2733 for Default_Switches ("Ada") use ("-O1", "-g");
2734 for Switches ("a_file1.adb") use ("-O0");
2741 for Default_Switches ("Ada") use ("-O0");
2747 for Default_Switches ("Ada") use ("-O3", "-gnatn");
2748 for Switches ("c_file1.adb") use ("-O0", "-g");
2753 then the following switches are used:
2756 @item all files from project A except a_file1.adb are compiled
2757 with "-O2 -g", since the aggregate project has priority.
2758 @item the file a_file1.adb is compiled with
2759 "-O0", since the Compiler.Switches has priority
2760 @item all files from project B are compiled with
2761 "-O2", since the aggregate project has priority
2762 @item all files from C are compiled with "-O2 -gnatn", except for
2763 c_file1.adb which is compiled with "-O0 -g"
2766 Even though C is seen through two paths (through A and through
2767 B), the switches used by the compiler are unambiguous.
2769 @item @b{Global_Configuration_Pragmas}
2770 @cindex @code{Global_Configuration_Pragmas}
2772 This attribute can be used to specify a file containing
2773 configuration pragmas, to be passed to the compiler. Since we
2774 ignore the package Builder in other aggregate projects and projects,
2775 only those pragmas defined in the main aggregate project will be
2778 Projects can locally add to those by using the
2779 @code{Compiler.Local_Configuration_Pragmas} attribute if they need.
2783 For projects that are built through the aggregate, the package Builder
2784 is ignored, except for the Executable attribute which specifies the
2785 name of the executables resulting from the link of the main programs, and
2786 for the Executable_Suffix.
2788 @c ---------------------------------------------
2789 @node Aggregate Library Projects
2790 @section Aggregate Library Projects
2791 @c ---------------------------------------------
2795 Aggregate library projects make it possible to build a single library
2796 using object files built using other standard or library
2797 projects. This gives the flexibility to describe an application as
2798 having multiple modules (a GUI, database access, ...) using different
2799 project files (so possibly built with different compiler options) and
2800 yet create a single library (static or relocatable) out of the
2801 corresponding object files.
2804 * Building aggregate library projects::
2805 * Syntax of aggregate library projects::
2808 @c ---------------------------------------------
2809 @node Building aggregate library projects
2810 @subsection Building aggregate library projects
2811 @c ---------------------------------------------
2813 For example, we can define an aggregate project Agg that groups A, B
2816 @smallexample @c projectfile
2817 aggregate library project Agg is
2818 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2819 for Library_Name use ("agg");
2820 for Library_Dir use ("lagg");
2824 Then, when you build with:
2830 This will build all units from projects A, B and C and will create a
2831 static library named @file{libagg.a} into the @file{lagg}
2832 directory. An aggregate library project has the same set of
2833 restriction as a standard library project.
2835 Note that a shared aggregate library project cannot aggregates a
2836 static library project. In platforms where a compiler option is
2837 required to create relocatable object files, a Builder package in the
2838 aggregate library project may be used:
2840 @smallexample @c projectfile
2841 aggregate library project Agg is
2842 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2843 for Library_Name use ("agg");
2844 for Library_Dir use ("lagg");
2845 for Library_Kind use "relocatable";
2848 for Global_Compilation_Switches ("Ada") use ("-fPIC");
2853 With the above aggregate library Builder package, the @code{-fPIC}
2854 option will be passed to the compiler when building any source code
2855 from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}.
2857 @c ---------------------------------------------
2858 @node Syntax of aggregate library projects
2859 @subsection Syntax of aggregate library projects
2860 @c ---------------------------------------------
2862 An aggregate library project follows the general syntax of project
2863 files. The recommended extension is still @file{.gpr}. However, a special
2864 @code{aggregate library} qualifier must be put before the keyword
2867 An aggregate library project cannot @code{with} any other project
2868 (standard or aggregate), except an abstract project which can be used
2869 to share attribute values.
2871 An aggregate library project does not have any source files directly (only
2872 through other standard projects). Therefore a number of the standard
2873 attributes and packages are forbidden in an aggregate library
2874 project. Here is the (non exhaustive) list:
2878 @item Source_Files, Source_List_File and other attributes dealing with
2880 @item Source_Dirs, Exec_Dir and Object_Dir
2883 @item Externally_Built
2884 @item Inherit_Source_Path
2885 @item Excluded_Source_Dirs
2886 @item Locally_Removed_Files
2887 @item Excluded_Source_Files
2888 @item Excluded_Source_List_File
2892 The only package that is authorized (albeit optional) is Builder.
2894 The Project_Files attribute (See @pxref{Aggregate Projects}) is used to
2895 described the aggregated projects whose object files have to be
2896 included into the aggregate library.
2898 @c ---------------------------------------------
2899 @node Project File Reference
2900 @section Project File Reference
2901 @c ---------------------------------------------
2904 This section describes the syntactic structure of project files, the various
2905 constructs that can be used. Finally, it ends with a summary of all available
2909 * Project Declaration::
2910 * Qualified Projects::
2915 * Typed String Declaration::
2921 @c ---------------------------------------------
2922 @node Project Declaration
2923 @subsection Project Declaration
2924 @c ---------------------------------------------
2927 Project files have an Ada-like syntax. The minimal project file is:
2929 @smallexample @c projectfile
2937 The identifier @code{Empty} is the name of the project.
2938 This project name must be present after the reserved
2939 word @code{end} at the end of the project file, followed by a semi-colon.
2941 @b{Identifiers} (i.e.@: the user-defined names such as project or variable names)
2942 have the same syntax as Ada identifiers: they must start with a letter,
2943 and be followed by zero or more letters, digits or underscore characters;
2944 it is also illegal to have two underscores next to each other. Identifiers
2945 are always case-insensitive ("Name" is the same as "name").
2948 simple_name ::= identifier
2949 name ::= simple_name @{ . simple_name @}
2953 @b{Strings} are used for values of attributes or as indexes for these
2954 attributes. They are in general case sensitive, except when noted
2955 otherwise (in particular, strings representing file names will be case
2956 insensitive on some systems, so that "file.adb" and "File.adb" both
2957 represent the same file).
2959 @b{Reserved words} are the same as for standard Ada 95, and cannot
2960 be used for identifiers. In particular, the following words are currently
2961 used in project files, but others could be added later on. In bold are the
2962 extra reserved words in project files: @code{all, at, case, end, for, is,
2963 limited, null, others, package, renames, type, use, when, with, @b{extends},
2964 @b{external}, @b{project}}.
2966 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2967 hyphens through the end of the line.
2969 A project may be an @b{independent project}, entirely defined by a single
2970 project file. Any source file in an independent project depends only
2971 on the predefined library and other source files in the same project.
2972 But a project may also depend on other projects, either by importing them
2973 through @b{with clauses}, or by @b{extending} at most one other project. Both
2974 types of dependency can be used in the same project.
2976 A path name denotes a project file. It can be absolute or relative.
2977 An absolute path name includes a sequence of directories, in the syntax of
2978 the host operating system, that identifies uniquely the project file in the
2979 file system. A relative path name identifies the project file, relative
2980 to the directory that contains the current project, or relative to a
2981 directory listed in the environment variables ADA_PROJECT_PATH and
2982 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2983 operating system are case sensitive. As a special case, the directory
2984 separator can always be "/" even on Windows systems, so that project files
2985 can be made portable across architectures.
2986 The syntax of the environment variable ADA_PROJECT_PATH and
2987 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2988 semicolons on Windows.
2990 A given project name can appear only once in a context clause.
2992 It is illegal for a project imported by a context clause to refer, directly
2993 or indirectly, to the project in which this context clause appears (the
2994 dependency graph cannot contain cycles), except when one of the with clause
2995 in the cycle is a @b{limited with}.
2996 @c ??? Need more details here
2998 @smallexample @c projectfile
2999 with "other_project.gpr";
3000 project My_Project extends "extended.gpr" is
3005 These dependencies form a @b{directed graph}, potentially cyclic when using
3006 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
3009 A project's @b{immediate sources} are the source files directly defined by
3010 that project, either implicitly by residing in the project source directories,
3011 or explicitly through any of the source-related attributes.
3012 More generally, a project sources are the immediate sources of the project
3013 together with the immediate sources (unless overridden) of any
3014 project on which it depends directly or indirectly.
3016 A @b{project hierarchy} can be created, where projects are children of
3017 other projects. The name of such a child project must be @code{Parent.Child},
3018 where @code{Parent} is the name of the parent project. In particular, this
3019 makes all @code{with} clauses of the parent project automatically visible
3020 in the child project.
3023 project ::= context_clause project_declaration
3025 context_clause ::= @{with_clause@}
3026 with_clause ::= @i{with} path_name @{ , path_name @} ;
3027 path_name ::= string_literal
3029 project_declaration ::= simple_project_declaration | project_extension
3030 simple_project_declaration ::=
3031 @i{project} @i{<project_>}name @i{is}
3032 @{declarative_item@}
3033 @i{end} <project_>simple_name;
3036 @c ---------------------------------------------
3037 @node Qualified Projects
3038 @subsection Qualified Projects
3039 @c ---------------------------------------------
3042 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
3043 is identifiers or reserved words, to qualify the project.
3044 The current list of qualifiers is:
3047 @item @b{abstract}: qualifies a project with no sources. Such a
3048 project must either have no declaration of attributes @code{Source_Dirs},
3049 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
3050 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
3051 as empty. If it extends another project, the project it extends must also be a
3052 qualified abstract project.
3053 @item @b{standard}: a standard project is a non library project with sources.
3054 This is the default (implicit) qualifier.
3055 @item @b{aggregate}: a project whose sources are aggregated from other
3057 @item @b{aggregate library}: a library whose sources are aggregated
3058 from other project or library project files.
3059 @item @b{library}: a library project must declare both attributes
3060 @code{Library_Name} and @code{Library_Dir}.
3061 @item @b{configuration}: a configuration project cannot be in a project tree.
3062 It describes compilers and other tools to @command{gprbuild}.
3065 @c ---------------------------------------------
3067 @subsection Declarations
3068 @c ---------------------------------------------
3071 Declarations introduce new entities that denote types, variables, attributes,
3072 and packages. Some declarations can only appear immediately within a project
3073 declaration. Others can appear within a project or within a package.
3076 declarative_item ::= simple_declarative_item
3077 | typed_string_declaration
3078 | package_declaration
3080 simple_declarative_item ::= variable_declaration
3081 | typed_variable_declaration
3082 | attribute_declaration
3086 empty_declaration ::= @i{null} ;
3090 An empty declaration is allowed anywhere a declaration is allowed. It has
3093 @c ---------------------------------------------
3095 @subsection Packages
3096 @c ---------------------------------------------
3099 A project file may contain @b{packages}, that group attributes (typically
3100 all the attributes that are used by one of the GNAT tools).
3102 A package with a given name may only appear once in a project file.
3103 The following packages are currently supported in project files
3104 (See @pxref{Attributes} for the list of attributes that each can contain).
3108 This package specifies characteristics useful when invoking the binder either
3109 directly via the @command{gnat} driver or when using a builder such as
3110 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
3112 This package specifies the compilation options used when building an
3113 executable or a library for a project. Most of the options should be
3114 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
3115 but there are some general options that should be defined in this
3116 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
3119 This package specifies the options used when calling the checking tool
3120 @command{gnatcheck} via the @command{gnat} driver. Its attribute
3121 @b{Default_Switches} has the same semantics as for the package
3122 @code{Builder}. The first string should always be @code{-rules} to specify
3123 that all the other options belong to the @code{-rules} section of the
3124 parameters to @command{gnatcheck}.
3126 This package specifies the compilation options used by the compiler for
3127 each languages. @xref{Tools Options in Project Files}.
3128 @item Cross_Reference
3129 This package specifies the options used when calling the library tool
3130 @command{gnatxref} via the @command{gnat} driver. Its attributes
3131 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3132 package @code{Builder}.
3134 This package specifies the options used when calling the tool
3135 @command{gnatelim} via the @command{gnat} driver. Its attributes
3136 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3137 package @code{Builder}.
3139 This package specifies the options used when calling the search tool
3140 @command{gnatfind} via the @command{gnat} driver. Its attributes
3141 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3142 package @code{Builder}.
3144 This package the options to use when invoking @command{gnatls} via the
3145 @command{gnat} driver.
3147 This package specifies the options used when calling the tool
3148 @command{gnatstub} via the @command{gnat} driver. Its attributes
3149 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3150 package @code{Builder}.
3152 This package specifies the options used when starting an integrated
3153 development environment, for instance @command{GPS} or @command{Gnatbench}.
3154 @xref{The Development Environments}.
3156 This package specifies the options used when installing a project
3157 with @command{gprinstall}. @xref{Installation}.
3159 This package specifies the options used by the linker.
3160 @xref{Main Subprograms}.
3162 @cindex Makefile package in projects
3163 This package is used by the GPS plugin Makefile.py. See the documentation
3164 in that plugin (from GPS: /Tools/Plug-ins).
3166 This package specifies the options used when calling the tool
3167 @command{gnatmetric} via the @command{gnat} driver. Its attributes
3168 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3169 package @code{Builder}.
3171 This package specifies the naming conventions that apply
3172 to the source files in a project. In particular, these conventions are
3173 used to automatically find all source files in the source directories,
3174 or given a file name to find out its language for proper processing.
3175 @xref{Naming Schemes}.
3176 @item Pretty_Printer
3177 This package specifies the options used when calling the formatting tool
3178 @command{gnatpp} via the @command{gnat} driver. Its attributes
3179 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3180 package @code{Builder}.
3182 This package specifies the options used when calling the tool
3183 @command{gnatstack} via the @command{gnat} driver. Its attributes
3184 @b{Default_Switches} and @b{Switches} have the same semantics as for the
3185 package @code{Builder}.
3187 This package specifies the options used when calling the tool
3188 @command{gnatsync} via the @command{gnat} driver.
3192 In its simplest form, a package may be empty:
3194 @smallexample @c projectfile
3204 A package may contain @b{attribute declarations},
3205 @b{variable declarations} and @b{case constructions}, as will be
3208 When there is ambiguity between a project name and a package name,
3209 the name always designates the project. To avoid possible confusion, it is
3210 always a good idea to avoid naming a project with one of the
3211 names allowed for packages or any name that starts with @code{gnat}.
3213 A package can also be defined by a @b{renaming declaration}. The new package
3214 renames a package declared in a different project file, and has the same
3215 attributes as the package it renames. The name of the renamed package
3216 must be the same as the name of the renaming package. The project must
3217 contain a package declaration with this name, and the project
3218 must appear in the context clause of the current project, or be its parent
3219 project. It is not possible to add or override attributes to the renaming
3220 project. If you need to do so, you should use an @b{extending declaration}
3223 Packages that are renamed in other project files often come from project files
3224 that have no sources: they are just used as templates. Any modification in the
3225 template will be reflected automatically in all the project files that rename
3226 a package from the template. This is a very common way to share settings
3229 Finally, a package can also be defined by an @b{extending declaration}. This is
3230 similar to a @b{renaming declaration}, except that it is possible to add or
3231 override attributes.
3234 package_declaration ::= package_spec | package_renaming | package_extension
3236 @i{package} @i{<package_>}simple_name @i{is}
3237 @{simple_declarative_item@}
3238 @i{end} package_identifier ;
3239 package_renaming ::==
3240 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
3241 package_extension ::==
3242 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
3243 @{simple_declarative_item@}
3244 @i{end} package_identifier ;
3247 @c ---------------------------------------------
3249 @subsection Expressions
3250 @c ---------------------------------------------
3253 An expression is any value that can be assigned to an attribute or a
3254 variable. It is either a literal value, or a construct requiring runtime
3255 computation by the project manager. In a project file, the computed value of
3256 an expression is either a string or a list of strings.
3258 A string value is one of:
3260 @item A literal string, for instance @code{"comm/my_proj.gpr"}
3261 @item The name of a variable that evaluates to a string (@pxref{Variables})
3262 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
3263 @item An external reference (@pxref{External Values})
3264 @item A concatenation of the above, as in @code{"prefix_" & Var}.
3269 A list of strings is one of the following:
3272 @item A parenthesized comma-separated list of zero or more string expressions, for
3273 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
3274 @item The name of a variable that evaluates to a list of strings
3275 @item The name of an attribute that evaluates to a list of strings
3276 @item A concatenation of a list of strings and a string (as defined above), for
3277 instance @code{("A", "B") & "C"}
3278 @item A concatenation of two lists of strings
3283 The following is the grammar for expressions
3286 string_literal ::= "@{string_element@}" -- Same as Ada
3287 string_expression ::= string_literal
3290 | attribute_reference
3291 | ( string_expression @{ & string_expression @} )
3292 string_list ::= ( string_expression @{ , string_expression @} )
3293 | @i{string_variable}_name
3294 | @i{string_}attribute_reference
3295 term ::= string_expression | string_list
3296 expression ::= term @{ & term @} -- Concatenation
3300 Concatenation involves strings and list of strings. As soon as a list of
3301 strings is involved, the result of the concatenation is a list of strings. The
3302 following Ada declarations show the existing operators:
3304 @smallexample @c ada
3305 function "&" (X : String; Y : String) return String;
3306 function "&" (X : String_List; Y : String) return String_List;
3307 function "&" (X : String_List; Y : String_List) return String_List;
3311 Here are some specific examples:
3313 @smallexample @c projectfile
3315 List := () & File_Name; -- One string in this list
3316 List2 := List & (File_Name & ".orig"); -- Two strings
3317 Big_List := List & Lists2; -- Three strings
3318 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
3322 @c ---------------------------------------------
3323 @node External Values
3324 @subsection External Values
3325 @c ---------------------------------------------
3328 An external value is an expression whose value is obtained from the command
3329 that invoked the processing of the current project file (typically a
3330 @command{gnatmake} or @command{gprbuild} command).
3332 There are two kinds of external values, one that returns a single string, and
3333 one that returns a string list.
3335 The syntax of a single string external value is:
3338 external_value ::= @i{external} ( string_literal [, string_literal] )
3342 The first string_literal is the string to be used on the command line or
3343 in the environment to specify the external value. The second string_literal,
3344 if present, is the default to use if there is no specification for this
3345 external value either on the command line or in the environment.
3347 Typically, the external value will either exist in the
3348 ^environment variables^logical name^
3349 or be specified on the command line through the
3350 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
3351 are specified, then the command line value is used, so that a user can more
3352 easily override the value.
3354 The function @code{external} always returns a string. It is an error if the
3355 value was not found in the environment and no default was specified in the
3356 call to @code{external}.
3358 An external reference may be part of a string expression or of a string
3359 list expression, and can therefore appear in a variable declaration or
3360 an attribute declaration.
3362 Most of the time, this construct is used to initialize typed variables, which
3363 are then used in @b{case} statements to control the value assigned to
3364 attributes in various scenarios. Thus such variables are often called
3365 @b{scenario variables}.
3367 The syntax for a string list external value is:
3370 external_value ::= @i{external_as_list} ( string_literal , string_literal )
3374 The first string_literal is the string to be used on the command line or
3375 in the environment to specify the external value. The second string_literal is
3376 the separator between each component of the string list.
3378 If the external value does not exist in the environment or on the command line,
3379 the result is an empty list. This is also the case, if the separator is an
3380 empty string or if the external value is only one separator.
3382 Any separator at the beginning or at the end of the external value is
3383 discarded. Then, if there is no separator in the external value, the result is
3384 a string list with only one string. Otherwise, any string between the beginning
3385 and the first separator, between two consecutive separators and between the
3386 last separator and the end are components of the string list.
3389 @i{external_as_list} ("SWITCHES", ",")
3393 If the external value is "-O2,-g", the result is ("-O2", "-g").
3395 If the external value is ",-O2,-g,", the result is also ("-O2", "-g").
3397 if the external value is "-gnav", the result is ("-gnatv").
3399 If the external value is ",,", the result is ("").
3401 If the external value is ",", the result is (), the empty string list.
3403 @c ---------------------------------------------
3404 @node Typed String Declaration
3405 @subsection Typed String Declaration
3406 @c ---------------------------------------------
3409 A @b{type declaration} introduces a discrete set of string literals.
3410 If a string variable is declared to have this type, its value
3411 is restricted to the given set of literals. These are the only named
3412 types in project files. A string type may only be declared at the project
3413 level, not inside a package.
3416 typed_string_declaration ::=
3417 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
3421 The string literals in the list are case sensitive and must all be different.
3422 They may include any graphic characters allowed in Ada, including spaces.
3423 Here is an example of a string type declaration:
3425 @smallexample @c projectfile
3426 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
3430 Variables of a string type are called @b{typed variables}; all other
3431 variables are called @b{untyped variables}. Typed variables are
3432 particularly useful in @code{case} constructions, to support conditional
3433 attribute declarations. (@pxref{Case Statements}).
3435 A string type may be referenced by its name if it has been declared in the same
3436 project file, or by an expanded name whose prefix is the name of the project
3437 in which it is declared.
3439 @c ---------------------------------------------
3441 @subsection Variables
3442 @c ---------------------------------------------
3445 @b{Variables} store values (strings or list of strings) and can appear
3446 as part of an expression. The declaration of a variable creates the
3447 variable and assigns the value of the expression to it. The name of the
3448 variable is available immediately after the assignment symbol, if you
3449 need to reuse its old value to compute the new value. Before the completion
3450 of its first declaration, the value of a variable defaults to the empty
3453 A @b{typed} variable can be used as part of a @b{case} expression to
3454 compute the value, but it can only be declared once in the project file,
3455 so that all case statements see the same value for the variable. This
3456 provides more consistency and makes the project easier to understand.
3457 The syntax for its declaration is identical to the Ada syntax for an
3458 object declaration. In effect, a typed variable acts as a constant.
3460 An @b{untyped} variable can be declared and overridden multiple times
3461 within the same project. It is declared implicitly through an Ada
3462 assignment. The first declaration establishes the kind of the variable
3463 (string or list of strings) and successive declarations must respect
3464 the initial kind. Assignments are executed in the order in which they
3465 appear, so the new value replaces the old one and any subsequent reference
3466 to the variable uses the new value.
3468 A variable may be declared at the project file level, or within a package.
3471 typed_variable_declaration ::=
3472 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
3473 variable_declaration ::= @i{<variable_>}simple_name := expression;
3477 Here are some examples of variable declarations:
3479 @smallexample @c projectfile
3481 This_OS : OS := external ("OS"); -- a typed variable declaration
3482 That_OS := "GNU/Linux"; -- an untyped variable declaration
3484 Name := "readme.txt";
3485 Save_Name := Name & ".saved";
3488 List_With_One_Element := ("-gnaty");
3489 List_With_Two_Elements := List_With_One_Element & "-gnatg";
3490 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
3495 A @b{variable reference} may take several forms:
3498 @item The simple variable name, for a variable in the current package (if any)
3499 or in the current project
3500 @item An expanded name, whose prefix is a context name.
3505 A @b{context} may be one of the following:
3508 @item The name of an existing package in the current project
3509 @item The name of an imported project of the current project
3510 @item The name of an ancestor project (i.e., a project extended by the current
3511 project, either directly or indirectly)
3512 @item An expanded name whose prefix is an imported/parent project name, and
3513 whose selector is a package name in that project.
3516 @c ---------------------------------------------
3518 @subsection Attributes
3519 @c ---------------------------------------------
3522 A project (and its packages) may have @b{attributes} that define
3523 the project's properties. Some attributes have values that are strings;
3524 others have values that are string lists.
3527 attribute_declaration ::=
3528 simple_attribute_declaration | indexed_attribute_declaration
3529 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
3530 indexed_attribute_declaration ::=
3531 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
3532 attribute_designator ::=
3533 @i{<simple_attribute_>}simple_name
3534 | @i{<indexed_attribute_>}simple_name ( string_literal )
3538 There are two categories of attributes: @b{simple attributes}
3539 and @b{indexed attributes}.
3540 Each simple attribute has a default value: the empty string (for string
3541 attributes) and the empty list (for string list attributes).
3542 An attribute declaration defines a new value for an attribute, and overrides
3543 the previous value. The syntax of a simple attribute declaration is similar to
3544 that of an attribute definition clause in Ada.
3546 Some attributes are indexed. These attributes are mappings whose
3547 domain is a set of strings. They are declared one association
3548 at a time, by specifying a point in the domain and the corresponding image
3550 Like untyped variables and simple attributes, indexed attributes
3551 may be declared several times. Each declaration supplies a new value for the
3552 attribute, and replaces the previous setting.
3554 Here are some examples of attribute declarations:
3556 @smallexample @c projectfile
3557 -- simple attributes
3558 for Object_Dir use "objects";
3559 for Source_Dirs use ("units", "test/drivers");
3561 -- indexed attributes
3562 for Body ("main") use "Main.ada";
3563 for Switches ("main.ada") use ("-v", "-gnatv");
3564 for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
3566 -- indexed attributes copy (from package Builder in project Default)
3567 -- The package name must always be specified, even if it is the current
3569 for Default_Switches use Default.Builder'Default_Switches;
3573 Attributes references may be appear anywhere in expressions, and are used
3574 to retrieve the value previously assigned to the attribute. If an attribute
3575 has not been set in a given package or project, its value defaults to the
3576 empty string or the empty list.
3579 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
3580 attribute_prefix ::= @i{project}
3581 | @i{<project_>}simple_name
3582 | package_identifier
3583 | @i{<project_>}simple_name . package_identifier
3589 @smallexample @c projectfile
3591 Naming'Dot_Replacement
3592 Imported_Project'Source_Dirs
3593 Imported_Project.Naming'Casing
3594 Builder'Default_Switches ("Ada")
3598 The prefix of an attribute may be:
3601 @item @code{project} for an attribute of the current project
3602 @item The name of an existing package of the current project
3603 @item The name of an imported project
3604 @item The name of a parent project that is extended by the current project
3605 @item An expanded name whose prefix is imported/parent project name,
3606 and whose selector is a package name
3611 Legal attribute names are listed below, including the package in
3612 which they must be declared. These names are case-insensitive. The
3613 semantics for the attributes is explained in great details in other sections.
3615 The column @emph{index} indicates whether the attribute is an indexed attribute,
3616 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
3617 system (file). The text is between brackets ([]) if the index is optional.
3619 @multitable @columnfractions .3 .1 .2 .4
3620 @headitem Attribute Name @tab Value @tab Package @tab Index
3621 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
3622 @item Name @tab string @tab - @tab (Read-only, name of project)
3623 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
3624 @item Source_Files @tab list @tab - @tab -
3625 @item Source_Dirs @tab list @tab - @tab -
3626 @item Source_List_File @tab string @tab - @tab -
3627 @item Locally_Removed_Files @tab list @tab - @tab -
3628 @item Excluded_Source_Files @tab list @tab - @tab -
3629 @item Object_Dir @tab string @tab - @tab -
3630 @item Exec_Dir @tab string @tab - @tab -
3631 @item Excluded_Source_Dirs @tab list @tab - @tab -
3632 @item Excluded_Source_Files @tab list @tab - @tab -
3633 @item Excluded_Source_List_File @tab list @tab - @tab -
3634 @item Inherit_Source_Path @tab list @tab - @tab insensitive
3635 @item Languages @tab list @tab - @tab -
3636 @item Main @tab list @tab - @tab -
3637 @item Main_Language @tab string @tab - @tab -
3638 @item Externally_Built @tab string @tab - @tab -
3639 @item Roots @tab list @tab - @tab file
3641 Library-related attributes @tab @tab @tab @pxref{Library Projects}
3642 @item Library_Dir @tab string @tab - @tab -
3643 @item Library_Name @tab string @tab - @tab -
3644 @item Library_Kind @tab string @tab - @tab -
3645 @item Library_Version @tab string @tab - @tab -
3646 @item Library_Interface @tab string @tab - @tab -
3647 @item Library_Auto_Init @tab string @tab - @tab -
3648 @item Library_Options @tab list @tab - @tab -
3649 @item Leading_Library_Options @tab list @tab - @tab -
3650 @item Library_Src_Dir @tab string @tab - @tab -
3651 @item Library_ALI_Dir @tab string @tab - @tab -
3652 @item Library_GCC @tab string @tab - @tab -
3653 @item Library_Symbol_File @tab string @tab - @tab -
3654 @item Library_Symbol_Policy @tab string @tab - @tab -
3655 @item Library_Reference_Symbol_File @tab string @tab - @tab -
3656 @item Interfaces @tab list @tab - @tab -
3658 Naming @tab @tab @tab @pxref{Naming Schemes}
3659 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
3660 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
3661 @item Separate_Suffix @tab string @tab Naming @tab -
3662 @item Casing @tab string @tab Naming @tab -
3663 @item Dot_Replacement @tab string @tab Naming @tab -
3664 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
3665 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
3666 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
3667 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
3669 Building @tab @tab @tab @pxref{Switches and Project Files}
3670 @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)
3671 @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)
3672 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
3673 @item Local_Config_File @tab string @tab insensitive @tab -
3674 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
3675 @item Global_Compilation_Switches @tab list @tab Builder @tab language
3676 @item Executable @tab string @tab Builder @tab [file]
3677 @item Executable_Suffix @tab string @tab Builder @tab -
3678 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
3680 IDE (used and created by GPS) @tab @tab @tab
3681 @item Remote_Host @tab string @tab IDE @tab -
3682 @item Program_Host @tab string @tab IDE @tab -
3683 @item Communication_Protocol @tab string @tab IDE @tab -
3684 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
3685 @item Debugger_Command @tab string @tab IDE @tab -
3686 @item Gnatlist @tab string @tab IDE @tab -
3687 @item Gnat @tab string @tab IDE @tab -
3688 @item VCS_Kind @tab string @tab IDE @tab -
3689 @item VCS_File_Check @tab string @tab IDE @tab -
3690 @item VCS_Log_Check @tab string @tab IDE @tab -
3691 @item Documentation_Dir @tab string @tab IDE @tab -
3693 Configuration files @tab @tab @tab See gprbuild manual
3694 @item Default_Language @tab string @tab - @tab -
3695 @item Run_Path_Option @tab list @tab - @tab -
3696 @item Run_Path_Origin @tab string @tab - @tab -
3697 @item Separate_Run_Path_Options @tab string @tab - @tab -
3698 @item Toolchain_Version @tab string @tab - @tab insensitive
3699 @item Toolchain_Description @tab string @tab - @tab insensitive
3700 @item Object_Generated @tab string @tab - @tab insensitive
3701 @item Objects_Linked @tab string @tab - @tab insensitive
3702 @item Target @tab string @tab - @tab -
3703 @item Library_Builder @tab string @tab - @tab -
3704 @item Library_Support @tab string @tab - @tab -
3705 @item Archive_Builder @tab list @tab - @tab -
3706 @item Archive_Builder_Append_Option @tab list @tab - @tab -
3707 @item Archive_Indexer @tab list @tab - @tab -
3708 @item Archive_Suffix @tab string @tab - @tab -
3709 @item Library_Partial_Linker @tab list @tab - @tab -
3710 @item Shared_Library_Prefix @tab string @tab - @tab -
3711 @item Shared_Library_Suffix @tab string @tab - @tab -
3712 @item Symbolic_Link_Supported @tab string @tab - @tab -
3713 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
3714 @item Library_Auto_Init_Supported @tab string @tab - @tab -
3715 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
3716 @item Library_Version_Switches @tab list @tab - @tab -
3717 @item Library_Install_Name_Option @tab string @tab - @tab -
3718 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
3719 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
3720 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
3721 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
3722 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3723 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3724 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
3725 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
3726 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
3727 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
3728 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
3729 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitive (language)
3730 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
3731 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
3732 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
3733 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
3734 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
3735 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3736 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3737 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
3738 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3739 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3740 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
3741 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
3742 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
3743 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
3744 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
3745 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
3746 @item Prefix @tab string @tab Binder @tab insensitive (language)
3747 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
3748 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
3749 @item Linker_Options @tab list @tab Linker @tab -
3750 @item Leading_Switches @tab list @tab Linker @tab -
3751 @item Map_File_Options @tab string @tab Linker @tab -
3752 @item Executable_Switches @tab list @tab Linker @tab -
3753 @item Lib_Dir_Switch @tab string @tab Linker @tab -
3754 @item Lib_Name_Switch @tab string @tab Linker @tab -
3755 @item Max_Command_Line_Length @tab string @tab Linker @tab -
3756 @item Response_File_Format @tab string @tab Linker @tab -
3757 @item Response_File_Switches @tab list @tab Linker @tab -
3760 @c ---------------------------------------------
3761 @node Case Statements
3762 @subsection Case Statements
3763 @c ---------------------------------------------
3766 A @b{case} statement is used in a project file to effect conditional
3767 behavior. Through this statement, you can set the value of attributes
3768 and variables depending on the value previously assigned to a typed
3771 All choices in a choice list must be distinct. Unlike Ada, the choice
3772 lists of all alternatives do not need to include all values of the type.
3773 An @code{others} choice must appear last in the list of alternatives.
3775 The syntax of a @code{case} construction is based on the Ada case statement
3776 (although the @code{null} statement for empty alternatives is optional).
3778 The case expression must be a typed string variable, whose value is often
3779 given by an external reference (@pxref{External Values}).
3781 Each alternative starts with the reserved word @code{when}, either a list of
3782 literal strings separated by the @code{"|"} character or the reserved word
3783 @code{others}, and the @code{"=>"} token.
3784 Each literal string must belong to the string type that is the type of the
3786 After each @code{=>}, there are zero or more statements. The only
3787 statements allowed in a case construction are other case statements,
3788 attribute declarations and variable declarations. String type declarations and
3789 package declarations are not allowed. Variable declarations are restricted to
3790 variables that have already been declared before the case construction.
3794 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
3797 @i{when} discrete_choice_list =>
3799 | attribute_declaration
3800 | variable_declaration
3801 | empty_declaration@}
3803 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
3807 Here is a typical example:
3809 @smallexample @c projectfile
3812 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
3813 OS : OS_Type := external ("OS", "GNU/Linux");
3817 when "GNU/Linux" | "Unix" =>
3818 for Switches ("Ada") use ("-gnath");
3820 for Switches ("Ada") use ("-gnatP");
3829 @c ---------------------------------------------
3830 @node Tools Supporting Project Files
3831 @chapter Tools Supporting Project Files
3832 @c ---------------------------------------------
3837 * gnatmake and Project Files::
3838 * The GNAT Driver and Project Files::
3839 * The Development Environments::
3842 @c ---------------------------------------------
3843 @node gnatmake and Project Files
3844 @section gnatmake and Project Files
3845 @c ---------------------------------------------
3848 This section covers several topics related to @command{gnatmake} and
3849 project files: defining ^switches^switches^ for @command{gnatmake}
3850 and for the tools that it invokes; specifying configuration pragmas;
3851 the use of the @code{Main} attribute; building and rebuilding library project
3855 * Switches Related to Project Files::
3856 * Switches and Project Files::
3857 * Specifying Configuration Pragmas::
3858 * Project Files and Main Subprograms::
3859 * Library Project Files::
3862 @c ---------------------------------------------
3863 @node Switches Related to Project Files
3864 @subsection Switches Related to Project Files
3865 @c ---------------------------------------------
3868 The following switches are used by GNAT tools that support project files:
3872 @item ^-P^/PROJECT_FILE=^@var{project}
3873 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
3874 Indicates the name of a project file. This project file will be parsed with
3875 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
3876 if any, and using the external references indicated
3877 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
3879 There may zero, one or more spaces between @option{-P} and @var{project}.
3882 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3884 Since the Project Manager parses the project file only after all the switches
3885 on the command line are checked, the order of the switches
3886 @option{^-P^/PROJECT_FILE^},
3887 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3888 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3890 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3891 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3892 Indicates that external variable @var{name} has the value @var{value}.
3893 The Project Manager will use this value for occurrences of
3894 @code{external(name)} when parsing the project file.
3897 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3905 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3906 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3907 @var{name}, only the last one is used.
3909 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3910 takes precedence over the value of the same name in the environment.
3912 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3913 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3914 Indicates the verbosity of the parsing of GNAT project files.
3917 @option{-vP0} means Default;
3918 @option{-vP1} means Medium;
3919 @option{-vP2} means High.
3923 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3927 The default is ^Default^DEFAULT^: no output for syntactically correct
3929 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3930 only the last one is used.
3932 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3933 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3934 Add directory <dir> at the beginning of the project search path, in order,
3935 after the current working directory.
3939 @cindex @option{-eL} (any project-aware tool)
3940 Follow all symbolic links when processing project files.
3943 @item ^--subdirs^/SUBDIRS^=<subdir>
3944 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3945 This switch is recognized by @command{gnatmake} and @command{gnatclean}. It
3946 indicate that the real directories (except the source directories) are the
3947 subdirectories <subdir> of the directories specified in the project files.
3948 This applies in particular to object directories, library directories and
3949 exec directories. If the subdirectories do not exist, they are created
3954 @c ---------------------------------------------
3955 @node Switches and Project Files
3956 @subsection Switches and Project Files
3957 @c ---------------------------------------------
3961 It is not currently possible to specify VMS style qualifiers in the project
3962 files; only Unix style ^switches^switches^ may be specified.
3965 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3966 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3967 attribute, a @code{Switches} attribute, or both;
3968 as their names imply, these ^switch^switch^-related
3969 attributes affect the ^switches^switches^ that are used for each of these GNAT
3971 @command{gnatmake} is invoked. As will be explained below, these
3972 component-specific ^switches^switches^ precede
3973 the ^switches^switches^ provided on the @command{gnatmake} command line.
3975 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3976 indexed by language name (case insensitive) whose value is a string list.
3979 @smallexample @c projectfile
3982 for ^Default_Switches^Default_Switches^ ("Ada")
3983 use ("^-gnaty^-gnaty^",
3990 The @code{Switches} attribute is indexed on a file name (which may or may
3991 not be case sensitive, depending
3992 on the operating system) whose value is a string list. For example:
3994 @smallexample @c projectfile
3997 for Switches ("main1.adb")
3999 for Switches ("main2.adb")
4006 For the @code{Builder} package, the file names must designate source files
4007 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
4008 file names must designate @file{ALI} or source files for main subprograms.
4009 In each case just the file name without an explicit extension is acceptable.
4011 For each tool used in a program build (@command{gnatmake}, the compiler, the
4012 binder, and the linker), the corresponding package @dfn{contributes} a set of
4013 ^switches^switches^ for each file on which the tool is invoked, based on the
4014 ^switch^switch^-related attributes defined in the package.
4015 In particular, the ^switches^switches^
4016 that each of these packages contributes for a given file @var{f} comprise:
4019 @item the value of attribute @code{Switches (@var{f})},
4020 if it is specified in the package for the given file,
4021 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
4022 if it is specified in the package.
4027 If neither of these attributes is defined in the package, then the package does
4028 not contribute any ^switches^switches^ for the given file.
4030 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
4031 two sets, in the following order: those contributed for the file
4032 by the @code{Builder} package;
4033 and the switches passed on the command line.
4035 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
4036 the ^switches^switches^ passed to the tool comprise three sets,
4037 in the following order:
4041 the applicable ^switches^switches^ contributed for the file
4042 by the @code{Builder} package in the project file supplied on the command line;
4045 those contributed for the file by the package (in the relevant project file --
4046 see below) corresponding to the tool; and
4049 the applicable switches passed on the command line.
4052 The term @emph{applicable ^switches^switches^} reflects the fact that
4053 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
4054 tools, depending on the individual ^switch^switch^.
4056 @command{gnatmake} may invoke the compiler on source files from different
4057 projects. The Project Manager will use the appropriate project file to
4058 determine the @code{Compiler} package for each source file being compiled.
4059 Likewise for the @code{Binder} and @code{Linker} packages.
4061 As an example, consider the following package in a project file:
4063 @smallexample @c projectfile
4067 for ^Default_Switches^Default_Switches^ ("Ada")
4069 for Switches ("a.adb")
4071 for Switches ("b.adb")
4080 If @command{gnatmake} is invoked with this project file, and it needs to
4081 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
4082 @file{a.adb} will be compiled with the ^switch^switch^
4084 @file{b.adb} with ^switches^switches^
4086 and @option{^-gnaty^-gnaty^},
4087 and @file{c.adb} with @option{^-g^-g^}.
4089 The following example illustrates the ordering of the ^switches^switches^
4090 contributed by different packages:
4092 @smallexample @c projectfile
4096 for Switches ("main.adb")
4105 for Switches ("main.adb")
4113 If you issue the command:
4116 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
4120 then the compiler will be invoked on @file{main.adb} with the following
4121 sequence of ^switches^switches^
4124 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
4128 with the last @option{^-O^-O^}
4129 ^switch^switch^ having precedence over the earlier ones;
4130 several other ^switches^switches^
4131 (such as @option{^-c^-c^}) are added implicitly.
4133 The ^switches^switches^
4135 and @option{^-O1^-O1^} are contributed by package
4136 @code{Builder}, @option{^-O2^-O2^} is contributed
4137 by the package @code{Compiler}
4138 and @option{^-O0^-O0^} comes from the command line.
4140 The @option{^-g^-g^}
4141 ^switch^switch^ will also be passed in the invocation of
4144 A final example illustrates switch contributions from packages in different
4147 @smallexample @c projectfile
4150 for Source_Files use ("pack.ads", "pack.adb");
4152 for ^Default_Switches^Default_Switches^ ("Ada")
4153 use ("^-gnata^-gnata^");
4161 for Source_Files use ("foo_main.adb", "bar_main.adb");
4163 for Switches ("foo_main.adb")
4173 procedure Foo_Main is
4182 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
4186 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
4187 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
4188 @option{^-gnato^-gnato^} (passed on the command line).
4189 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
4190 are @option{^-g^-g^} from @code{Proj4.Builder},
4191 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
4192 and @option{^-gnato^-gnato^} from the command line.
4194 When using @command{gnatmake} with project files, some ^switches^switches^ or
4195 arguments may be expressed as relative paths. As the working directory where
4196 compilation occurs may change, these relative paths are converted to absolute
4197 paths. For the ^switches^switches^ found in a project file, the relative paths
4198 are relative to the project file directory, for the switches on the command
4199 line, they are relative to the directory where @command{gnatmake} is invoked.
4200 The ^switches^switches^ for which this occurs are:
4206 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
4208 ^-o^-o^, object files specified in package @code{Linker} or after
4209 -largs on the command line). The exception to this rule is the ^switch^switch^
4210 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
4212 @c ---------------------------------------------
4213 @node Specifying Configuration Pragmas
4214 @subsection Specifying Configuration Pragmas
4215 @c ---------------------------------------------
4218 When using @command{gnatmake} with project files, if there exists a file
4219 @file{gnat.adc} that contains configuration pragmas, this file will be
4222 Configuration pragmas can be defined by means of the following attributes in
4223 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
4224 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
4226 Both these attributes are single string attributes. Their values is the path
4227 name of a file containing configuration pragmas. If a path name is relative,
4228 then it is relative to the project directory of the project file where the
4229 attribute is defined.
4231 When compiling a source, the configuration pragmas used are, in order,
4232 those listed in the file designated by attribute
4233 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
4234 project file, if it is specified, and those listed in the file designated by
4235 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
4236 the project file of the source, if it exists.
4238 @c ---------------------------------------------
4239 @node Project Files and Main Subprograms
4240 @subsection Project Files and Main Subprograms
4241 @c ---------------------------------------------
4244 When using a project file, you can invoke @command{gnatmake}
4245 with one or several main subprograms, by specifying their source files on the
4249 gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb
4253 Each of these needs to be a source file of the same project, except
4254 when the switch ^-u^/UNIQUE^ is used.
4256 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
4257 same project, one of the project in the tree rooted at the project specified
4258 on the command line. The package @code{Builder} of this common project, the
4259 "main project" is the one that is considered by @command{gnatmake}.
4261 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
4262 imported directly or indirectly by the project specified on the command line.
4263 Note that if such a source file is not part of the project specified on the
4264 command line, the ^switches^switches^ found in package @code{Builder} of the
4265 project specified on the command line, if any, that are transmitted
4266 to the compiler will still be used, not those found in the project file of
4269 When using a project file, you can also invoke @command{gnatmake} without
4270 explicitly specifying any main, and the effect depends on whether you have
4271 defined the @code{Main} attribute. This attribute has a string list value,
4272 where each element in the list is the name of a source file (the file
4273 extension is optional) that contains a unit that can be a main subprogram.
4275 If the @code{Main} attribute is defined in a project file as a non-empty
4276 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
4277 line, then invoking @command{gnatmake} with this project file but without any
4278 main on the command line is equivalent to invoking @command{gnatmake} with all
4279 the file names in the @code{Main} attribute on the command line.
4282 @smallexample @c projectfile
4285 for Main use ("main1.adb", "main2.adb", "main3.adb");
4291 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
4293 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}.
4295 When the project attribute @code{Main} is not specified, or is specified
4296 as an empty string list, or when the switch @option{-u} is used on the command
4297 line, then invoking @command{gnatmake} with no main on the command line will
4298 result in all immediate sources of the project file being checked, and
4299 potentially recompiled. Depending on the presence of the switch @option{-u},
4300 sources from other project files on which the immediate sources of the main
4301 project file depend are also checked and potentially recompiled. In other
4302 words, the @option{-u} switch is applied to all of the immediate sources of the
4305 When no main is specified on the command line and attribute @code{Main} exists
4306 and includes several mains, or when several mains are specified on the
4307 command line, the default ^switches^switches^ in package @code{Builder} will
4308 be used for all mains, even if there are specific ^switches^switches^
4309 specified for one or several mains.
4311 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
4312 the specific ^switches^switches^ for each main, if they are specified.
4314 @c ---------------------------------------------
4315 @node Library Project Files
4316 @subsection Library Project Files
4317 @c ---------------------------------------------
4320 When @command{gnatmake} is invoked with a main project file that is a library
4321 project file, it is not allowed to specify one or more mains on the command
4324 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
4325 ^-l^/ACTION=LINK^ have special meanings.
4328 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
4329 to @command{gnatmake} that @command{gnatbind} should be invoked for the
4332 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
4333 to @command{gnatmake} that the binder generated file should be compiled
4334 (in the case of a stand-alone library) and that the library should be built.
4337 @c ---------------------------------------------
4338 @node The GNAT Driver and Project Files
4339 @section The GNAT Driver and Project Files
4340 @c ---------------------------------------------
4343 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
4344 can benefit from project files:
4345 (@command{^gnatbind^gnatbind^},
4346 @command{^gnatcheck^gnatcheck^},
4347 @command{^gnatclean^gnatclean^},
4348 @command{^gnatelim^gnatelim^},
4349 @command{^gnatfind^gnatfind^},
4350 @command{^gnatlink^gnatlink^},
4351 @command{^gnatls^gnatls^},
4352 @command{^gnatmetric^gnatmetric^},
4353 @command{^gnatpp^gnatpp^},
4354 @command{^gnatstub^gnatstub^},
4355 and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
4356 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
4357 They must be invoked through the @command{gnat} driver.
4359 The @command{gnat} driver is a wrapper that accepts a number of commands and
4360 calls the corresponding tool. It was designed initially for VMS platforms (to
4361 convert VMS qualifiers to Unix-style switches), but it is now available on all
4364 On non-VMS platforms, the @command{gnat} driver accepts the following commands
4368 @item BIND to invoke @command{^gnatbind^gnatbind^}
4369 @item CHOP to invoke @command{^gnatchop^gnatchop^}
4370 @item CLEAN to invoke @command{^gnatclean^gnatclean^}
4371 @item COMP or COMPILE to invoke the compiler
4372 @item ELIM to invoke @command{^gnatelim^gnatelim^}
4373 @item FIND to invoke @command{^gnatfind^gnatfind^}
4374 @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
4375 @item LINK to invoke @command{^gnatlink^gnatlink^}
4376 @item LS or LIST to invoke @command{^gnatls^gnatls^}
4377 @item MAKE to invoke @command{^gnatmake^gnatmake^}
4378 @item NAME to invoke @command{^gnatname^gnatname^}
4379 @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
4380 @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
4381 @item METRIC to invoke @command{^gnatmetric^gnatmetric^}
4382 @item STUB to invoke @command{^gnatstub^gnatstub^}
4383 @item XREF to invoke @command{^gnatxref^gnatxref^}
4388 (note that the compiler is invoked using the command
4389 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
4391 On non-VMS platforms, between @command{gnat} and the command, two
4392 special switches may be used:
4395 @item @command{-v} to display the invocation of the tool.
4396 @item @command{-dn} to prevent the @command{gnat} driver from removing
4397 the temporary files it has created. These temporary files are
4398 configuration files and temporary file list files.
4403 The command may be followed by switches and arguments for the invoked
4407 gnat bind -C main.ali
4413 Switches may also be put in text files, one switch per line, and the text
4414 files may be specified with their path name preceded by '@@'.
4417 gnat bind @@args.txt main.ali
4421 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
4422 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
4423 (@option{^-P^/PROJECT_FILE^},
4424 @option{^-X^/EXTERNAL_REFERENCE^} and
4425 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
4426 the switches of the invoking tool.
4428 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
4429 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
4430 the immediate sources of the specified project file.
4432 When GNAT METRIC is used with a project file, but with no source
4433 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
4434 with all the immediate sources of the specified project file and with
4435 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
4438 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
4439 a project file, no source is specified on the command line and
4440 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
4441 the underlying tool (^gnatpp^gnatpp^ or
4442 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
4443 not only for the immediate sources of the main project.
4445 (-U stands for Universal or Union of the project files of the project tree)
4448 For each of the following commands, there is optionally a corresponding
4449 package in the main project.
4452 @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
4454 @item package @code{Check} for command CHECK (invoking
4455 @code{^gnatcheck^gnatcheck^})
4457 @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
4459 @item package @code{Cross_Reference} for command XREF (invoking
4460 @code{^gnatxref^gnatxref^})
4462 @item package @code{Eliminate} for command ELIM (invoking
4463 @code{^gnatelim^gnatelim^})
4465 @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
4467 @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
4469 @item package @code{Gnatstub} for command STUB
4470 (invoking @code{^gnatstub^gnatstub^})
4472 @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
4474 @item package @code{Check} for command CHECK
4475 (invoking @code{^gnatcheck^gnatcheck^})
4477 @item package @code{Metrics} for command METRIC
4478 (invoking @code{^gnatmetric^gnatmetric^})
4480 @item package @code{Pretty_Printer} for command PP or PRETTY
4481 (invoking @code{^gnatpp^gnatpp^})
4486 Package @code{Gnatls} has a unique attribute @code{Switches},
4487 a simple variable with a string list value. It contains ^switches^switches^
4488 for the invocation of @code{^gnatls^gnatls^}.
4490 @smallexample @c projectfile
4503 All other packages have two attribute @code{Switches} and
4504 @code{^Default_Switches^Default_Switches^}.
4506 @code{Switches} is an indexed attribute, indexed by the
4507 source file name, that has a string list value: the ^switches^switches^ to be
4508 used when the tool corresponding to the package is invoked for the specific
4511 @code{^Default_Switches^Default_Switches^} is an attribute,
4512 indexed by the programming language that has a string list value.
4513 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
4514 ^switches^switches^ for the invocation of the tool corresponding
4515 to the package, except if a specific @code{Switches} attribute
4516 is specified for the source file.
4518 @smallexample @c projectfile
4522 for Source_Dirs use ("**");
4533 for ^Default_Switches^Default_Switches^ ("Ada")
4534 use ("^-gnatv^-gnatv^",
4535 "^-gnatwa^-gnatwa^");
4541 for ^Default_Switches^Default_Switches^ ("Ada")
4549 for ^Default_Switches^Default_Switches^ ("Ada")
4551 for Switches ("main.adb")
4560 for ^Default_Switches^Default_Switches^ ("Ada")
4567 package Cross_Reference is
4568 for ^Default_Switches^Default_Switches^ ("Ada")
4573 end Cross_Reference;
4579 With the above project file, commands such as
4582 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
4583 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
4584 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
4585 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
4586 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
4590 will set up the environment properly and invoke the tool with the switches
4591 found in the package corresponding to the tool:
4592 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
4593 except @code{Switches ("main.adb")}
4594 for @code{^gnatlink^gnatlink^}.
4595 It is also possible to invoke some of the tools,
4596 (@code{^gnatcheck^gnatcheck^},
4597 @code{^gnatmetric^gnatmetric^},
4598 and @code{^gnatpp^gnatpp^})
4599 on a set of project units thanks to the combination of the switches
4600 @option{-P}, @option{-U} and possibly the main unit when one is interested
4601 in its closure. For instance,
4607 will compute the metrics for all the immediate units of project
4610 gnat metric -Pproj -U
4614 will compute the metrics for all the units of the closure of projects
4615 rooted at @code{proj}.
4617 gnat metric -Pproj -U main_unit
4621 will compute the metrics for the closure of units rooted at
4622 @code{main_unit}. This last possibility relies implicitly
4623 on @command{gnatbind}'s option @option{-R}. But if the argument files for the
4624 tool invoked by the @command{gnat} driver are explicitly specified
4625 either directly or through the tool @option{-files} option, then the tool
4626 is called only for these explicitly specified files.
4628 @c ---------------------------------------------
4629 @node The Development Environments
4630 @section The Development Environments
4631 @c ---------------------------------------------
4634 See the appropriate manuals for more details. These environments will
4635 store a number of settings in the project itself, when they are meant
4636 to be shared by the whole team working on the project. Here are the
4637 attributes defined in the package @b{IDE} in projects.
4641 This is a simple attribute. Its value is a string that designates the remote
4642 host in a cross-compilation environment, to be used for remote compilation and
4643 debugging. This field should not be specified when running on the local
4647 This is a simple attribute. Its value is a string that specifies the
4648 name of IP address of the embedded target in a cross-compilation environment,
4649 on which the program should execute.
4651 @item Communication_Protocol
4652 This is a simple string attribute. Its value is the name of the protocol
4653 to use to communicate with the target in a cross-compilation environment,
4654 e.g.@: @code{"wtx"} or @code{"vxworks"}.
4656 @item Compiler_Command
4657 This is an associative array attribute, whose domain is a language name. Its
4658 value is string that denotes the command to be used to invoke the compiler.
4659 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
4660 @command{gnatmake}, in particular in the handling of switches.
4662 @item Debugger_Command
4663 This is simple attribute, Its value is a string that specifies the name of
4664 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
4666 @item Default_Switches
4667 This is an associative array attribute. Its indexes are the name of the
4668 external tools that the GNAT Programming System (GPS) is supporting. Its
4669 value is a list of switches to use when invoking that tool.
4672 This is a simple attribute. Its value is a string that specifies the name
4673 of the @command{gnatls} utility to be used to retrieve information about the
4674 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
4677 This is a simple attribute. Its value is a string used to specify the
4678 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
4679 ClearCase or Perforce.
4682 This is a simple attribute. Its value is a string that specifies the name
4683 of the @command{gnat} utility to be used when executing various tools from
4684 GPS, in particular @code{"gnat pp"}, @code{"gnat stub"},@dots{}
4686 @item VCS_File_Check
4687 This is a simple attribute. Its value is a string that specifies the
4688 command used by the VCS to check the validity of a file, either
4689 when the user explicitly asks for a check, or as a sanity check before
4693 This is a simple attribute. Its value is a string that specifies
4694 the command used by the VCS to check the validity of a log file.
4696 @item VCS_Repository_Root
4697 The VCS repository root path. This is used to create tags or branches
4698 of the repository. For subversion the value should be the @code{URL}
4699 as specified to check-out the working copy of the repository.
4701 @item VCS_Patch_Root
4702 The local root directory to use for building patch file. All patch chunks
4703 will be relative to this path. The root project directory is used if
4704 this value is not defined.