1 @set gprconfig GPRconfig
3 @c ------ projects.texi
4 @c This file is shared between the GNAT user's guide and gprbuild. It is not
5 @c compilable on its own, you should instead compile the other two manuals.
6 @c For that reason, there is no toplevel @menu
8 @c ---------------------------------------------
9 @node GNAT Project Manager
10 @chapter GNAT Project Manager
11 @c ---------------------------------------------
16 * Building With Projects::
17 * Organizing Projects into Subsystems::
18 * Scenarios in Projects::
21 * Aggregate Projects::
22 * Project File Reference::
25 @c ---------------------------------------------
28 @c ---------------------------------------------
31 This chapter describes GNAT's @emph{Project Manager}, a facility that allows
32 you to manage complex builds involving a number of source files, directories,
33 and options for different system configurations. In particular,
34 project files allow you to specify:
37 @item The directory or set of directories containing the source files, and/or the
38 names of the specific source files themselves
39 @item The directory in which the compiler's output
40 (@file{ALI} files, object files, tree files, etc.) is to be placed
41 @item The directory in which the executable programs are to be placed
42 @item Switch settings for any of the project-enabled tools;
43 you can apply these settings either globally or to individual compilation units.
44 @item The source files containing the main subprogram(s) to be built
45 @item The source programming language(s)
46 @item Source file naming conventions; you can specify these either globally or for
47 individual compilation units (@pxref{Naming Schemes}).
48 @item Change any of the above settings depending on external values, thus enabling
49 the reuse of the projects in various @b{scenarios} (@pxref{Scenarios
51 @item Automatically build libraries as part of the build process
52 (@pxref{Library Projects}).
57 Project files are written in a syntax close to that of Ada, using familiar
58 notions such as packages, context clauses, declarations, default values,
59 assignments, and inheritance (@pxref{Project File Reference}).
61 Project files can be built hierarchically from other project files, simplifying
62 complex system integration and project reuse (@pxref{Organizing Projects into
66 @item One project can import other projects containing needed source files.
67 More generally, the Project Manager lets you structure large development
68 efforts into hierarchical subsystems, where build decisions are delegated
69 to the subsystem level, and thus different compilation environments
70 (switch settings) used for different subsystems.
71 @item You can organize GNAT projects in a hierarchy: a child project
72 can extend a parent project, inheriting the parent's source files and
73 optionally overriding any of them with alternative versions
74 (@pxref{Project Extension}).
79 Several tools support project files, generally in addition to specifying
80 the information on the command line itself). They share common switches
81 to control the loading of the project (in particular
82 @option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
83 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).
84 @xref{Switches Related to Project Files}.
86 The Project Manager supports a wide range of development strategies,
87 for systems of all sizes. Here are some typical practices that are
91 @item Using a common set of source files and generating object files in different
92 directories via different switch settings. It can be used for instance, for
93 generating separate sets of object files for debugging and for production.
94 @item Using a mostly-shared set of source files with different versions of
95 some units or subunits. It can be used for instance, for grouping and hiding
99 all OS dependencies in a small number of implementation units.
101 Project files can be used to achieve some of the effects of a source
102 versioning system (for example, defining separate projects for
103 the different sets of sources that comprise different releases) but the
104 Project Manager is independent of any source configuration management tool
105 that might be used by the developers.
107 The various sections below introduce the different concepts related to
108 projects. Each section starts with examples and use cases, and then goes into
109 the details of related project file capabilities.
111 @c ---------------------------------------------
112 @node Building With Projects
113 @section Building With Projects
114 @c ---------------------------------------------
117 In its simplest form, a unique project is used to build a single executable.
118 This section concentrates on such a simple setup. Later sections will extend
119 this basic model to more complex setups.
121 The following concepts are the foundation of project files, and will be further
122 detailed later in this documentation. They are summarized here as a reference.
125 @item @b{Project file}:
126 A text file using an Ada-like syntax, generally using the @file{.gpr}
127 extension. It defines build-related characteristics of an application.
128 The characteristics include the list of sources, the location of those
129 sources, the location for the generated object files, the name of
130 the main program, and the options for the various tools involved in the
133 @item @b{Project attribute}:
134 A specific project characteristic is defined by an attribute clause. Its
135 value is a string or a sequence of strings. All settings in a project
136 are defined through a list of predefined attributes with precise
137 semantics. @xref{Attributes}.
139 @item @b{Package in a project}:
140 Global attributes are defined at the top level of a project.
141 Attributes affecting specific tools are grouped in a
142 package whose name is related to tool's function. The most common
143 packages are @code{Builder}, @code{Compiler}, @code{Binder},
144 and @code{Linker}. @xref{Packages}.
146 @item @b{Project variables}:
147 In addition to attributes, a project can use variables to store intermediate
148 values and avoid duplication in complex expressions. It can be initialized
149 with a value coming from the environment.
150 A frequent use of variables is to define scenarios.
151 @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.
153 @item @b{Source files} and @b{source directories}:
154 A source file is associated with a language through a naming convention. For
155 instance, @code{foo.c} is typically the name of a C source file;
156 @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a
157 file containing an Ada spec. A compilation unit is often composed of a main
158 source file and potentially several auxiliary ones, such as header files in C.
159 The naming conventions can be user defined @xref{Naming Schemes}, and will
160 drive the builder to call the appropriate compiler for the given source file.
161 Source files are searched for in the source directories associated with the
162 project through the @b{Source_Dirs} attribute. By default, all the files (in
163 these source directories) following the naming conventions associated with the
164 declared languages are considered to be part of the project. It is also
165 possible to limit the list of source files using the @b{Source_Files} or
166 @b{Source_List_File} attributes. Note that those last two attributes only
167 accept basenames with no directory information.
169 @item @b{Object files} and @b{object directory}:
170 An object file is an intermediate file produced by the compiler from a
171 compilation unit. It is used by post-compilation tools to produce
172 final executables or libraries. Object files produced in the context of
173 a given project are stored in a single directory that can be specified by the
174 @b{Object_Dir} attribute. In order to store objects in
175 two or more object directories, the system must be split into
176 distinct subsystems with their own project file.
180 The following subsections introduce gradually all the attributes of interest
181 for simple build needs. Here is the simple setup that will be used in the
184 The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in
185 the @file{common/} directory. The file @file{proc.adb} contains an Ada main
186 subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile
187 these source files with the switch @option{-O2}, and put the resulting files in
188 the directory @file{obj/}.
198 ^common/release/^[COMMON.RELEASE]^
199 proc.ali, proc.o pack.ali, pack.o
204 Our project is to be called @emph{Build}. The name of the
205 file is the name of the project (case-insensitive) with the
206 @file{.gpr} extension, therefore the project file name is @file{build.gpr}. This
207 is not mandatory, but a warning is issued when this convention is not followed.
209 This is a very simple example, and as stated above, a single project
210 file is enough for it. We will thus create a new file, that for now
211 should contain the following code:
214 @b{project} Build @b{is}
219 * Source Files and Directories::
220 * Object and Exec Directory::
222 * Tools Options in Project Files::
223 * Compiling with Project Files::
224 * Executable File Names::
225 * Avoid Duplication With Variables::
229 @c ---------------------------------------------
230 @node Source Files and Directories
231 @subsection Source Files and Directories
232 @c ---------------------------------------------
235 When you create a new project, the first thing to describe is how to find the
236 corresponding source files. This is the only settings that are needed by all
237 the tools that will use this project (builder, compiler, binder and linker for
238 the compilation, IDEs to edit the source files,@dots{}).
240 @cindex Source directories
241 First step is to declare the source directories, which are the directories
242 to be searched to find source files. In the case of the example,
243 the @file{common} directory is the only source directory.
245 @cindex @code{Source_Dirs}
246 There are several ways of defining source directories:
249 @item When the attribute @b{Source_Dirs} is not used, a project contains a
250 single source directory which is the one where the project file itself
251 resides. In our example, if @file{build.gpr} is placed in the @file{common}
252 directory, the project has the needed implicit source directory.
254 @item The attribute @b{Source_Dirs} can be set to a list of path names, one
255 for each of the source directories. Such paths can either be absolute
256 names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the
257 directory in which the project file resides (for instance "." if
258 @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
259 Each of the source directories must exist and be readable.
262 The syntax for directories is platform specific. For portability, however,
263 the project manager will always properly translate UNIX-like path names to
264 the native format of specific platform. For instance, when the same project
265 file is to be used both on Unix and Windows, "/" should be used as the
266 directory separator rather than "\".
268 @item The attribute @b{Source_Dirs} can automatically include subdirectories
269 using a special syntax inspired by some UNIX shells. If any of the path in
270 the list ends with @emph{"**"}, then that path and all its subdirectories
271 (recursively) are included in the list of source directories. For instance,
272 @file{**} and @file{./**} represent the complete directory tree rooted at ".".
273 @cindex Source directories, recursive
275 @cindex @code{Excluded_Source_Dirs}
276 When using that construct, it can sometimes be convenient to also use the
277 attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry
278 specifies a directory whose immediate content, not including subdirs, is to
279 be excluded. It is also possible to exclude a complete directory subtree
280 using the "**" notation.
282 @cindex @code{Ignore_Source_Sub_Dirs}
283 It is often desirable to remove, from the source directories, directory
284 subtrees rooted at some subdirectories. An example is the subdirectories
285 created by a Version Control System such as Subversion that creates directory
286 subtrees .svn/**. To do that, attribute @b{Ignore_Source_Sub_Dirs} can be
287 used. It specifies the list of simple file names for the root of these
288 undesirable directory subtrees.
293 When applied to the simple example, and because we generally prefer to have
294 the project file at the toplevel directory rather than mixed with the sources,
295 we will create the following file
299 @b{project} Build @b{is}
300 @b{for} Source_Dirs @b{use} ("common"); -- <<<<
305 Once source directories have been specified, one may need to indicate
306 source files of interest. By default, all source files present in the source
307 directories are considered by the project manager. When this is not desired,
308 it is possible to specify the list of sources to consider explicitly.
309 In such a case, only source file base names are indicated and not
310 their absolute or relative path names. The project manager is in charge of
311 locating the specified source files in the specified source directories.
314 @item By default, the project manager search for all source files of all
315 specified languages in all the source directories.
317 Since the project manager was initially developed for Ada environments, the
318 default language is usually Ada and the above project file is complete: it
319 defines without ambiguity the sources composing the project: that is to say,
320 all the sources in subdirectory "common" for the default language (Ada) using
321 the default naming convention.
323 @cindex @code{Languages}
324 However, when compiling a multi-language application, or a pure C
325 application, the project manager must be told which languages are of
326 interest, which is done by setting the @b{Languages} attribute to a list of
327 strings, each of which is the name of a language. Tools like
328 @command{gnatmake} only know about Ada, while other tools like
329 @command{gprbuild} know about many more languages such as C, C++, Fortran,
330 assembly and others can be added dynamically.
332 @cindex Naming scheme
333 Even when using only Ada, the default naming might not be suitable. Indeed,
334 how does the project manager recognizes an "Ada file" from any other
335 file? Project files can describe the naming scheme used for source files,
336 and override the default (@pxref{Naming Schemes}). The default is the
337 standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
338 specs), which is what is used in our example, explaining why no naming scheme
339 is explicitly specified.
340 @xref{Naming Schemes}.
342 @item @code{Source Files}
343 @cindex @code{Source_Files}
344 In some cases, source directories might contain files that should not be
345 included in a project. One can specify the explicit list of file names to
346 be considered through the @b{Source_Files} attribute.
347 When this attribute is defined, instead of looking at every file in the
348 source directories, the project manager takes only those names into
349 consideration reports errors if they cannot be found in the source
350 directories or does not correspond to the naming scheme.
352 @item For various reasons, it is sometimes useful to have a project with no
353 sources (most of the time because the attributes defined in the project
354 file will be reused in other projects, as explained in @pxref{Organizing
355 Projects into Subsystems}. To do this, the attribute
356 @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
357 @emph{Source_Dirs} can be set to the empty list, with the same
360 @item @code{Source_List_File}
361 @cindex @code{Source_List_File}
362 If there is a great number of files, it might be more convenient to use
363 the attribute @b{Source_List_File}, which specifies the full path of a file.
364 This file must contain a list of source file names (one per line, no
365 directory information) that are searched as if they had been defined
366 through @emph{Source_Files}. Such a file can easily be created through
369 A warning is issued if both attributes @code{Source_Files} and
370 @code{Source_List_File} are given explicit values. In this case, the
371 attribute @code{Source_Files} prevails.
373 @item @code{Excluded_Source_Files}
374 @cindex @code{Excluded_Source_Files}
375 @cindex @code{Locally_Removed_Files}
376 @cindex @code{Excluded_Source_List_File}
377 Specifying an explicit list of files is not always convenient.It might be
378 more convenient to use the default search rules with specific exceptions.
379 This can be done thanks to the attribute @b{Excluded_Source_Files}
380 (or its synonym @b{Locally_Removed_Files}).
381 Its value is the list of file names that should not be taken into account.
382 This attribute is often used when extending a project, @xref{Project
383 Extension}. A similar attribute @b{Excluded_Source_List_File} plays the same
384 role but takes the name of file containing file names similarly to
385 @code{Source_List_File}.
390 In most simple cases, such as the above example, the default source file search
391 behavior provides the expected result, and we do not need to add anything after
392 setting @code{Source_Dirs}. The project manager automatically finds
393 @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the
396 Note that it is considered an error for a project file to have no sources
397 attached to it unless explicitly declared as mentioned above.
399 If the order of the source directories is known statically, that is if
400 @code{"**"} is not used in the string list @code{Source_Dirs}, then there may
401 be several files with the same source file name sitting in different
402 directories of the project. In this case, only the file in the first directory
403 is considered as a source of the project and the others are hidden. If
404 @code{"**"} is not used in the string list @code{Source_Dirs}, it is an error
405 to have several files with the same source file name in the same directory
406 @code{"**"} subtree, since there would be an ambiguity as to which one should
407 be used. However, two files with the same source file name may in two single
408 directories or directory subtrees. In this case, the one in the first directory
409 or directory subtree is a source of the project.
411 @c ---------------------------------------------
412 @node Object and Exec Directory
413 @subsection Object and Exec Directory
414 @c ---------------------------------------------
417 The next step when writing a project is to indicate where the compiler should
418 put the object files. In fact, the compiler and other tools might create
419 several different kind of files (for GNAT, there is the object file and the ALI
420 file for instance). One of the important concepts in projects is that most
421 tools may consider source directories as read-only and do not attempt to create
422 new or temporary files there. Instead, all files are created in the object
423 directory. It is of course not true for project-aware IDEs, whose purpose it is
424 to create the source files.
426 @cindex @code{Object_Dir}
427 The object directory is specified through the @b{Object_Dir} attribute.
428 Its value is the path to the object directory, either absolute or
429 relative to the directory containing the project file. This
430 directory must already exist and be readable and writable, although
431 some tools have a switch to create the directory if needed (See
432 the switch @code{-p} for @command{gnatmake} and @command{gprbuild}).
434 If the attribute @code{Object_Dir} is not specified, it defaults to
435 the project directory, that is the directory containing the project file.
437 For our example, we can specify the object dir in this way:
440 @b{project} Build @b{is}
441 @b{for} Source_Dirs @b{use} ("common");
442 @b{for} Object_Dir @b{use} "obj"; -- <<<<
447 As mentioned earlier, there is a single object directory per project. As a
448 result, if you have an existing system where the object files are spread in
449 several directories, you can either move all of them into the same directory if
450 you want to build it with a single project file, or study the section on
451 subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
452 separate object directory can be associated with one of the subsystem
453 constituting the application.
455 When the @command{linker} is called, it usually creates an executable. By
456 default, this executable is placed in the object directory of the project. It
457 might be convenient to store it in its own directory.
459 @cindex @code{Exec_Dir}
460 This can be done through the @code{Exec_Dir} attribute, which, like
461 @emph{Object_Dir} contains a single absolute or relative path and must point to
462 an existing and writable directory, unless you ask the tool to create it on
463 your behalf. When not specified, It defaults to the object directory and
464 therefore to the project file's directory if neither @emph{Object_Dir} nor
465 @emph{Exec_Dir} was specified.
467 In the case of the example, let's place the executable in the root
468 of the hierarchy, ie the same directory as @file{build.gpr}. Hence
469 the project file is now
472 @b{project} Build @b{is}
473 @b{for} Source_Dirs @b{use} ("common");
474 @b{for} Object_Dir @b{use} "obj";
475 @b{for} Exec_Dir @b{use} "."; -- <<<<
479 @c ---------------------------------------------
480 @node Main Subprograms
481 @subsection Main Subprograms
482 @c ---------------------------------------------
485 In the previous section, executables were mentioned. The project manager needs
486 to be taught what they are. In a project file, an executable is indicated by
487 pointing to source file of the main subprogram. In C this is the file that
488 contains the @code{main} function, and in Ada the file that contains the main
491 There can be any number of such main files within a given project, and thus
492 several executables can be built in the context of a single project file. Of
493 course, one given executable might not (and in fact will not) need all the
494 source files referenced by the project. As opposed to other build environments
495 such as @command{makefile}, one does not need to specify the list of
496 dependencies of each executable, the project-aware builders knows enough of the
497 semantics of the languages to build ands link only the necessary elements.
500 The list of main files is specified via the @b{Main} attribute. It contains
501 a list of file names (no directories). If a project defines this
502 attribute, it is not necessary to identify main files on the
503 command line when invoking a builder, and editors like
504 @command{GPS} will be able to create extra menus to spawn or debug the
505 corresponding executables.
508 @b{project} Build @b{is}
509 @b{for} Source_Dirs @b{use} ("common");
510 @b{for} Object_Dir @b{use} "obj";
511 @b{for} Exec_Dir @b{use} ".";
512 @b{for} Main @b{use} ("proc.adb"); -- <<<<
517 If this attribute is defined in the project, then spawning the builder
518 with a command such as
521 gnatmake ^-Pbuild^/PROJECT_FILE=build^
525 automatically builds all the executables corresponding to the files
526 listed in the @emph{Main} attribute. It is possible to specify one
527 or more executables on the command line to build a subset of them.
529 @c ---------------------------------------------
530 @node Tools Options in Project Files
531 @subsection Tools Options in Project Files
532 @c ---------------------------------------------
535 We now have a project file that fully describes our environment, and can be
536 used to build the application with a simple @command{gnatmake} command as seen
537 in the previous section. In fact, the empty project we showed immediately at
538 the beginning (with no attribute at all) could already fulfill that need if it
539 was put in the @file{common} directory.
541 Of course, we always want more control. This section will show you how to
542 specify the compilation switches that the various tools involved in the
543 building of the executable should use.
545 @cindex command line length
546 Since source names and locations are described into the project file, it is not
547 necessary to use switches on the command line for this purpose (switches such
548 as -I for gcc). This removes a major source of command line length overflow.
549 Clearly, the builders will have to communicate this information one way or
550 another to the underlying compilers and tools they call but they usually use
551 response files for this and thus should not be subject to command line
554 Several tools are participating to the creation of an executable: the compiler
555 produces object files from the source files; the binder (in the Ada case)
556 creates an source file that takes care, among other things, of elaboration
557 issues and global variables initialization; and the linker gathers everything
558 into a single executable that users can execute. All these tools are known by
559 the project manager and will be called with user defined switches from the
560 project files. However, we need to introduce a new project file concept to
561 express which switches to be used for any of the tools involved in the build.
563 @cindex project file packages
564 A project file is subdivided into zero or more @b{packages}, each of which
565 contains the attributes specific to one tool (or one set of tools). Project
566 files use an Ada-like syntax for packages. Package names permitted in project
567 files are restricted to a predefined set (@pxref{Packages}), and the contents
568 of packages are limited to a small set of constructs and attributes
569 (@pxref{Attributes}).
571 Our example project file can be extended with the following empty packages. At
572 this stage, they could all be omitted since they are empty, but they show which
573 packages would be involved in the build process.
576 @b{project} Build @b{is}
577 @b{for} Source_Dirs @b{use} ("common");
578 @b{for} Object_Dir @b{use} "obj";
579 @b{for} Exec_Dir @b{use} ".";
580 @b{for} Main @b{use} ("proc.adb");
583 @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
586 @b{package} Compiler @b{is} --<<< for the compiler
589 @b{package} Binder @b{is} --<<< for the binder
592 @b{package} Linker @b{is} --<<< for the linker
597 Let's first examine the compiler switches. As stated in the initial description
598 of the example, we want to compile all files with @option{-O2}. This is a
599 compiler switch, although it is usual, on the command line, to pass it to the
600 builder which then passes it to the compiler. It is recommended to use directly
601 the right package, which will make the setup easier to understand for other
604 Several attributes can be used to specify the switches:
607 @item @b{Default_Switches}:
608 @cindex @code{Default_Switches}
609 This is the first mention in this manual of an @b{indexed attribute}. When
610 this attribute is defined, one must supply an @emph{index} in the form of a
612 In the case of @emph{Default_Switches}, the index is the name of the
613 language to which the switches apply (since a different compiler will
614 likely be used for each language, and each compiler has its own set of
615 switches). The value of the attribute is a list of switches.
617 In this example, we want to compile all Ada source files with the
618 @option{-O2} switch, and the resulting project file is as follows
619 (only the @code{Compiler} package is shown):
622 @b{package} Compiler @b{is}
623 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
628 @cindex @code{Switches}
629 in some cases, we might want to use specific switches
630 for one or more files. For instance, compiling @file{proc.adb} might not be
631 possible at high level of optimization because of a compiler issue.
632 In such a case, the @emph{Switches}
633 attribute (indexed on the file name) can be used and will override the
634 switches defined by @emph{Default_Switches}. Our project file would
638 @b{package} Compiler @b{is}
639 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
640 @b{for} Switches ("proc.adb") @b{use} ("-O0");
645 @code{Switches} may take a pattern as an index, such as in:
648 @b{package} Compiler @b{is}
649 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
650 @b{for} Switches ("pkg*") @b{use} ("-O0");
655 Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0,
659 @code{Switches} can also be given a language name as index instead of a file
660 name in which case it has the same semantics as @emph{Default_Switches}.
661 However, indexes with wild cards are never valid for language name.
663 @item @b{Local_Configuration_Pragmas}:
664 @cindex @code{Local_Configuration_Pragmas}
665 this attribute may specify the path
666 of a file containing configuration pragmas for use by the Ada compiler,
667 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
668 used for all the sources of the project.
672 The switches for the other tools are defined in a similar manner through the
673 @b{Default_Switches} and @b{Switches} attributes, respectively in the
674 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
675 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
676 package (for linking executables).
678 @c ---------------------------------------------
679 @node Compiling with Project Files
680 @subsection Compiling with Project Files
681 @c ---------------------------------------------
684 Now that our project files are written, let's build our executable.
685 Here is the command we would use from the command line:
688 gnatmake ^-Pbuild^/PROJECT_FILE=build^
692 This will automatically build the executables specified through the
693 @emph{Main} attribute: for each, it will compile or recompile the
694 sources for which the object file does not exist or is not up-to-date; it
695 will then run the binder; and finally run the linker to create the
698 @command{gnatmake} only knows how to handle Ada files. By using
699 @command{gprbuild} as a builder, you could automatically manage C files the
700 same way: create the file @file{utils.c} in the @file{common} directory,
701 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
704 gprbuild ^-Pbuild^/PROJECT_FILE=build^
708 Gprbuild knows how to recompile the C files and will
709 recompile them only if one of their dependencies has changed. No direct
710 indication on how to build the various elements is given in the
711 project file, which describes the project properties rather than a
712 set of actions to be executed. Here is the invocation of
713 @command{gprbuild} when building a multi-language program:
726 Notice the three steps described earlier:
729 @item The first three gcc commands correspond to the compilation phase.
730 @item The gprbind command corresponds to the post-compilation phase.
731 @item The last gcc command corresponds to the final link.
736 @cindex @option{-v} option (for GPRbuild)
737 The default output of GPRbuild's execution is kept reasonably simple and easy
738 to understand. In particular, some of the less frequently used commands are not
739 shown, and some parameters are abbreviated. So it is not possible to rerun the
740 effect of the @command{gprbuild} command by cut-and-pasting its output.
741 GPRbuild's option @code{-v} provides a much more verbose output which includes,
742 among other information, more complete compilation, post-compilation and link
745 @c ---------------------------------------------
746 @node Executable File Names
747 @subsection Executable File Names
748 @c ---------------------------------------------
751 @cindex @code{Executable}
752 By default, the executable name corresponding to a main file is
753 computed from the main source file name. Through the attribute
754 @b{Builder.Executable}, it is possible to change this default.
756 For instance, instead of building @command{proc} (or @command{proc.exe}
757 on Windows), we could configure our project file to build "proc1"
758 (resp proc1.exe) with the following addition:
760 @smallexample @c projectfile
762 ... -- same as before
764 for Executable ("proc.adb") use "proc1";
770 @cindex @code{Executable_Suffix}
771 Attribute @b{Executable_Suffix}, when specified, may change the suffix
772 of the executable files, when no attribute @code{Executable} applies:
773 its value replace the platform-specific executable suffix.
774 The default executable suffix is empty on UNIX and ".exe" on Windows.
776 It is also possible to change the name of the produced executable by using the
777 command line switch @option{-o}. When several mains are defined in the project,
778 it is not possible to use the @option{-o} switch and the only way to change the
779 names of the executable is provided by Attributes @code{Executable} and
780 @code{Executable_Suffix}.
782 @c ---------------------------------------------
783 @node Avoid Duplication With Variables
784 @subsection Avoid Duplication With Variables
785 @c ---------------------------------------------
788 To illustrate some other project capabilities, here is a slightly more complex
789 project using similar sources and a main program in C:
791 @smallexample @c projectfile
793 for Languages use ("Ada", "C");
794 for Source_Dirs use ("common");
795 for Object_Dir use "obj";
796 for Main use ("main.c");
798 C_Switches := ("-pedantic");
799 for Default_Switches ("C") use C_Switches;
800 for Default_Switches ("Ada") use ("-gnaty");
801 for Switches ("main.c") use C_Switches & ("-g");
807 This project has many similarities with the previous one.
808 As expected, its @code{Main} attribute now refers to a C source.
809 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
810 executable will be put in the directory @file{obj}.
812 The most noticeable difference is the use of a variable in the
813 @emph{Compiler} package to store settings used in several attributes.
814 This avoids text duplication, and eases maintenance (a single place to
815 modify if we want to add new switches for C files). We will revisit
816 the use of variables in the context of scenarios (@pxref{Scenarios in
819 In this example, we see how the file @file{main.c} can be compiled with
820 the switches used for all the other C files, plus @option{-g}.
821 In this specific situation the use of a variable could have been
822 replaced by a reference to the @code{Default_Switches} attribute:
824 @smallexample @c projectfile
825 for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
829 Note the tick (@emph{'}) used to refer to attributes defined in a package.
831 Here is the output of the GPRbuild command using this project:
835 gcc -c -pedantic -g main.c
836 gcc -c -gnaty proc.adb
837 gcc -c -gnaty pack.adb
838 gcc -c -pedantic utils.c
845 The default switches for Ada sources,
846 the default switches for C sources (in the compilation of @file{lib.c}),
847 and the specific switches for @file{main.c} have all been taken into
850 @c ---------------------------------------------
852 @subsection Naming Schemes
853 @c ---------------------------------------------
856 Sometimes an Ada software system is ported from one compilation environment to
857 another (say GNAT), and the file are not named using the default GNAT
858 conventions. Instead of changing all the file names, which for a variety of
859 reasons might not be possible, you can define the relevant file naming scheme
860 in the @b{Naming} package of your project file.
862 The naming scheme has two distinct goals for the project manager: it
863 allows finding of source files when searching in the source
864 directories, and given a source file name it makes it possible to guess
865 the associated language, and thus the compiler to use.
867 Note that the use by the Ada compiler of pragmas Source_File_Name is not
868 supported when using project files. You must use the features described in this
869 paragraph. You can however specify other configuration pragmas
870 (@pxref{Specifying Configuration Pragmas}).
872 The following attributes can be defined in package @code{Naming}:
876 @cindex @code{Casing}
877 Its value must be one of @code{"lowercase"} (the default if
878 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
879 casing of file names with regards to the Ada unit name. Given an Ada unit
880 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
881 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
882 On Windows, file names are case insensitive, so this attribute is
885 @item @b{Dot_Replacement}:
886 @cindex @code{Dot_Replacement}
887 This attribute specifies the string that should replace the "." in unit
888 names. Its default value is @code{"-"} so that a unit
889 @code{Parent.Child} is expected to be found in the file
890 @file{parent-child.adb}. The replacement string must satisfy the following
891 requirements to avoid ambiguities in the naming scheme:
894 @item It must not be empty
895 @item It cannot start or end with an alphanumeric character
896 @item It cannot be a single underscore
897 @item It cannot start with an underscore followed by an alphanumeric
898 @item It cannot contain a dot @code{'.'} except if the entire string
903 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
904 @cindex @code{Spec_Suffix}
905 @cindex @code{Specification_Suffix}
906 For Ada, these attributes give the suffix used in file names that contain
907 specifications. For other languages, they give the extension for files
908 that contain declaration (header files in C for instance). The attribute
909 is indexed on the language.
910 The two attributes are equivalent, but the latter is obsolescent.
911 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
912 @code{"^.ads^.ADS^"}.
913 The value must satisfy the following requirements:
916 @item It must not be empty
917 @item It cannot start with an alphanumeric character
918 @item It cannot start with an underscore followed by an alphanumeric character
919 @item It must include at least one dot
923 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
924 @cindex @code{Body_Suffix}
925 @cindex @code{Implementation_Suffix}
926 These attributes give the extension used for file names that contain
927 code (bodies in Ada). They are indexed on the language. The second
928 version is obsolescent and fully replaced by the first attribute.
930 These attributes must satisfy the same requirements as @code{Spec_Suffix}.
931 In addition, they must be different from any of the values in
933 If @code{Body_Suffix ("Ada")} is not specified, then the default is
934 @code{"^.adb^.ADB^"}.
936 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
937 same string, then a file name that ends with the longest of these two
938 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
939 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
941 If the suffix does not start with a '.', a file with a name exactly equal
942 to the suffix will also be part of the project (for instance if you define
943 the suffix as @code{Makefile}, a file called @file{Makefile} will be part
944 of the project. This capability is usually not interesting when building.
945 However, it might become useful when a project is also used to
946 find the list of source files in an editor, like the GNAT Programming System
949 @item @b{Separate_Suffix}:
950 @cindex @code{Separate_Suffix}
951 This attribute is specific to Ada. It denotes the suffix used in file names
952 that contain separate bodies. If it is not specified, then it defaults to
953 same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the
954 @code{Body_Suffix} attribute. The only accepted index is "Ada".
956 @item @b{Spec} or @b{Specification}:
958 @cindex @code{Specification}
959 This attribute @code{Spec} can be used to define the source file name for a
960 given Ada compilation unit's spec. The index is the literal name of the Ada
961 unit (case insensitive). The value is the literal base name of the file that
962 contains this unit's spec (case sensitive or insensitive depending on the
963 operating system). This attribute allows the definition of exceptions to the
964 general naming scheme, in case some files do not follow the usual
967 When a source file contains several units, the relative position of the unit
968 can be indicated. The first unit in the file is at position 1
970 @smallexample @c projectfile
971 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
972 for Spec ("top") use "foo.a" at 1;
973 for Spec ("foo") use "foo.a" at 2;
976 @item @b{Body} or @b{Implementation}:
978 @cindex @code{Implementation}
979 These attribute play the same role as @emph{Spec} for Ada bodies.
981 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
982 @cindex @code{Specification_Exceptions}
983 @cindex @code{Implementation_Exceptions}
984 These attributes define exceptions to the naming scheme for languages
985 other than Ada. They are indexed on the language name, and contain
986 a list of file names respectively for headers and source code.
992 For example, the following package models the Apex file naming rules:
994 @smallexample @c projectfile
997 for Casing use "lowercase";
998 for Dot_Replacement use ".";
999 for Spec_Suffix ("Ada") use ".1.ada";
1000 for Body_Suffix ("Ada") use ".2.ada";
1007 For example, the following package models the DEC Ada file naming rules:
1009 @smallexample @c projectfile
1012 for Casing use "lowercase";
1013 for Dot_Replacement use "__";
1014 for Spec_Suffix ("Ada") use "_.ada";
1015 for Body_Suffix ("Ada") use ".ada";
1021 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1022 names in lower case)
1025 @c ---------------------------------------------
1026 @node Organizing Projects into Subsystems
1027 @section Organizing Projects into Subsystems
1028 @c ---------------------------------------------
1031 A @b{subsystem} is a coherent part of the complete system to be built. It is
1032 represented by a set of sources and one single object directory. A system can
1033 be composed of a single subsystem when it is simple as we have seen in the
1034 first section. Complex systems are usually composed of several interdependent
1035 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1036 other one is required to build it, and in particular if visibility on some of
1037 the sources of this other subsystem is required. Each subsystem is usually
1038 represented by its own project file.
1040 In this section, the previous example is being extended. Let's assume some
1041 sources of our @code{Build} project depend on other sources.
1042 For instance, when building a graphical interface, it is usual to depend upon
1043 a graphical library toolkit such as GtkAda. Furthermore, we also need
1044 sources from a logging module we had previously written.
1047 * Project Dependencies::
1048 * Cyclic Project Dependencies::
1049 * Sharing Between Projects::
1050 * Global Attributes::
1053 @c ---------------------------------------------
1054 @node Project Dependencies
1055 @subsection Project Dependencies
1056 @c ---------------------------------------------
1059 GtkAda comes with its own project file (appropriately called
1060 @file{gtkada.gpr}), and we will assume we have already built a project
1061 called @file{logging.gpr} for the logging module. With the information provided
1062 so far in @file{build.gpr}, building the application would fail with an error
1063 indicating that the gtkada and logging units that are relied upon by the sources
1064 of this project cannot be found.
1066 This is easily solved by adding the following @b{with} clauses at the beginning
1069 @smallexample @c projectfile
1071 with "a/b/logging.gpr";
1078 @cindex @code{Externally_Built}
1079 When such a project is compiled, @command{gnatmake} will automatically
1080 check the other projects and recompile their sources when needed. It will also
1081 recompile the sources from @code{Build} when needed, and finally create the
1082 executable. In some cases, the implementation units needed to recompile a
1083 project are not available, or come from some third-party and you do not want to
1084 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1085 "true" can be set, indicating to the builder that this project can be assumed
1086 to be up-to-date, and should not be considered for recompilation. In Ada, if
1087 the sources of this externally built project were compiled with another version
1088 of the compiler or with incompatible options, the binder will issue an error.
1090 The project's @code{with} clause has several effects. It provides source
1091 visibility between projects during the compilation process. It also guarantees
1092 that the necessary object files from @code{Logging} and @code{GtkAda} are
1093 available when linking @code{Build}.
1095 As can be seen in this example, the syntax for importing projects is similar
1096 to the syntax for importing compilation units in Ada. However, project files
1097 use literal strings instead of names, and the @code{with} clause identifies
1098 project files rather than packages.
1100 Each literal string after @code{with} is the path
1101 (absolute or relative) to a project file. The @code{.gpr} extension is
1102 optional, although we recommend adding it. If no extension is specified,
1103 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1104 the file is searched for exactly as written in the @code{with} clause,
1105 that is with no extension.
1107 As mentioned above, the path after a @code{with} has to be a literal
1108 string, and you cannot use concatenation, or lookup the value of external
1109 variables to change the directories from which a project is loaded.
1110 A solution if you need something like this is to use aggregate projects
1111 (@pxref{Aggregate Projects}).
1113 @cindex project path
1114 When a relative path or a base name is used, the
1115 project files are searched relative to each of the directories in the
1116 @b{project path}. This path includes all the directories found with the
1117 following algorithm, in that order, as soon as a matching file is found,
1121 @item First, the file is searched relative to the directory that contains the
1122 current project file.
1125 @cindex @code{ADA_PROJECT_PATH}
1126 @cindex @code{GPR_PROJECT_PATH}
1127 Then it is searched relative to all the directories specified in the
1128 ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and
1129 @b{ADA_PROJECT_PATH} (in that order) if they exist. The former is
1130 recommended, the latter is kept for backward compatibility.
1132 @item Finally, it is searched relative to the default project directories.
1133 Such directories depends on the tool used. The different locations searched
1134 in the specified order are:
1137 @item @file{<prefix>/<target>/lib/gnat}
1138 (for @command{gprbuild} only and if option @option{--target} is specified)
1139 @item @file{<prefix>/share/gpr/}
1140 (for @command{gnatmake} and @command{gprbuild})
1141 @item @file{<prefix>/lib/gnat/}
1142 (for @command{gnatmake} and @command{gprbuild})
1145 In our example, @file{gtkada.gpr} is found in the predefined directory if
1146 it was installed at the same root as GNAT.
1150 Some tools also support extending the project path from the command line,
1151 generally through the @option{-aP}. You can see the value of the project
1152 path by using the @command{gnatls -v} command.
1154 Any symbolic link will be fully resolved in the directory of the
1155 importing project file before the imported project file is examined.
1157 Any source file in the imported project can be used by the sources of the
1158 importing project, transitively.
1159 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1160 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1161 import @code{C} explicitly. However, this is not recommended, because if
1162 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1163 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1164 that will report such indirect dependencies.
1166 One very important aspect of a project hierarchy is that
1167 @b{a given source can only belong to one project} (otherwise the project manager
1168 would not know which settings apply to it and when to recompile it). It means
1169 that different project files do not usually share source directories or
1170 when they do, they need to specify precisely which project owns which sources
1171 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1172 can each own a source with the same base file name as long as they live in
1173 different directories. The latter is not true for Ada Sources because of the
1174 correlation between source files and Ada units.
1176 @c ---------------------------------------------
1177 @node Cyclic Project Dependencies
1178 @subsection Cyclic Project Dependencies
1179 @c ---------------------------------------------
1182 Cyclic dependencies are mostly forbidden:
1183 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1184 is not allowed to import @code{A}. However, there are cases when cyclic
1185 dependencies would be beneficial. For these cases, another form of import
1186 between projects exists: the @b{limited with}. A project @code{A} that
1187 imports a project @code{B} with a straight @code{with} may also be imported,
1188 directly or indirectly, by @code{B} through a @code{limited with}.
1190 The difference between straight @code{with} and @code{limited with} is that
1191 the name of a project imported with a @code{limited with} cannot be used in the
1192 project importing it. In particular, its packages cannot be renamed and
1193 its variables cannot be referred to.
1195 @smallexample @c 0projectfile
1199 For Exec_Dir use B'Exec_Dir; -- ok
1202 limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
1204 For Exec_Dir use A'Exec_Dir; -- not ok
1211 limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
1213 For Exec_Dir use A'Exec_Dir; -- not ok
1217 @c ---------------------------------------------
1218 @node Sharing Between Projects
1219 @subsection Sharing Between Projects
1220 @c ---------------------------------------------
1223 When building an application, it is common to have similar needs in several of
1224 the projects corresponding to the subsystems under construction. For instance,
1225 they will all have the same compilation switches.
1227 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1228 switches for all sources of a subsystem is simple: it is just a matter of
1229 adding a @code{Compiler.Default_Switches} attribute to each project files with
1230 the same value. Of course, that means duplication of data, and both places need
1231 to be changed in order to recompile the whole application with different
1232 switches. It can become a real problem if there are many subsystems and thus
1233 many project files to edit.
1235 There are two main approaches to avoiding this duplication:
1238 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1239 to reference the attribute in Logging, either through a package renaming,
1240 or by referencing the attribute. The following example shows both cases:
1242 @smallexample @c projectfile
1245 for Switches ("Ada") use ("-O2");
1248 for Switches ("Ada") use ("-E");
1254 package Compiler renames Logging.Compiler;
1256 for Switches ("Ada") use Logging.Binder'Switches ("Ada");
1262 The solution used for @code{Compiler} gets the same value for all
1263 attributes of the package, but you cannot modify anything from the
1264 package (adding extra switches or some exceptions). The second
1265 version is more flexible, but more verbose.
1267 If you need to refer to the value of a variable in an imported
1268 project, rather than an attribute, the syntax is similar but uses
1269 a "." rather than an apostrophe. For instance:
1271 @smallexample @c projectfile
1274 Var1 := Imported.Var;
1278 @item The second approach is to define the switches in a third project.
1279 That project is setup without any sources (so that, as opposed to
1280 the first example, none of the project plays a special role), and
1281 will only be used to define the attributes. Such a project is
1282 typically called @file{shared.gpr}.
1284 @smallexample @c projectfile
1285 abstract project Shared is
1286 for Source_Files use (); -- no project
1288 for Switches ("Ada") use ("-O2");
1294 package Compiler renames Shared.Compiler;
1299 package Compiler renames Shared.Compiler;
1304 As for the first example, we could have chosen to set the attributes
1305 one by one rather than to rename a package. The reason we explicitly
1306 indicate that @code{Shared} has no sources is so that it can be created
1307 in any directory and we are sure it shares no sources with @code{Build}
1308 or @code{Logging}, which of course would be invalid.
1310 @cindex project qualifier
1311 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1312 This qualifier is optional, but helps convey the message that we do not
1313 intend this project to have sources (@pxref{Qualified Projects} for
1318 @c ---------------------------------------------
1319 @node Global Attributes
1320 @subsection Global Attributes
1321 @c ---------------------------------------------
1324 We have already seen many examples of attributes used to specify a special
1325 option of one of the tools involved in the build process. Most of those
1326 attributes are project specific. That it to say, they only affect the invocation
1327 of tools on the sources of the project where they are defined.
1329 There are a few additional attributes that apply to all projects in a
1330 hierarchy as long as they are defined on the "main" project.
1331 The main project is the project explicitly mentioned on the command-line.
1332 The project hierarchy is the "with"-closure of the main project.
1334 Here is a list of commonly used global attributes:
1337 @item @b{Builder.Global_Configuration_Pragmas}:
1338 @cindex @code{Global_Configuration_Pragmas}
1339 This attribute points to a file that contains configuration pragmas
1340 to use when building executables. These pragmas apply for all
1341 executables build from this project hierarchy. As we have seen before,
1342 additional pragmas can be specified on a per-project basis by setting the
1343 @code{Compiler.Local_Configuration_Pragmas} attribute.
1345 @item @b{Builder.Global_Compilation_Switches}:
1346 @cindex @code{Global_Compilation_Switches}
1347 This attribute is a list of compiler switches to use when compiling any
1348 source file in the project hierarchy. These switches are used in addition
1349 to the ones defined in the @code{Compiler} package, which only apply to
1350 the sources of the corresponding project. This attribute is indexed on
1351 the name of the language.
1355 Using such global capabilities is convenient. It can also lead to unexpected
1356 behavior. Especially when several subsystems are shared among different main
1357 projects and the different global attributes are not
1358 compatible. Note that using aggregate projects can be a safer and more powerful
1359 replacement to global attributes.
1361 @c ---------------------------------------------
1362 @node Scenarios in Projects
1363 @section Scenarios in Projects
1364 @c ---------------------------------------------
1367 Various aspects of the projects can be modified based on @b{scenarios}. These
1368 are user-defined modes that change the behavior of a project. Typical
1369 examples are the setup of platform-specific compiler options, or the use of
1370 a debug and a release mode (the former would activate the generation of debug
1371 information, when the second will focus on improving code optimization).
1373 Let's enhance our example to support a debug and a release modes.The issue is to
1374 let the user choose what kind of system he is building:
1375 use @option{-g} as compiler switches in debug mode and @option{-O2}
1376 in release mode. We will also setup the projects so that we do not share the
1377 same object directory in both modes, otherwise switching from one to the other
1378 might trigger more recompilations than needed or mix objects from the 2 modes.
1380 One naive approach is to create two different project files, say
1381 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1382 attributes as explained in previous sections. This solution does not scale well,
1383 because in presence of multiple projects depending on each other,
1384 you will also have to duplicate the complete hierarchy and adapt the project
1385 files to point to the right copies.
1388 Instead, project files support the notion of scenarios controlled
1389 by external values. Such values can come from several sources (in decreasing
1393 @item @b{Command line}:
1395 When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1396 extra @option{-X} switches to define the external value. In
1397 our case, the command line might look like
1400 gnatmake -Pbuild.gpr -Xmode=debug
1401 or gnatmake -Pbuild.gpr -Xmode=release
1404 @item @b{^Environment variables^Logical names^}:
1405 When the external value does not come from the command line, it can come from
1406 the value of ^environment variables^logical names^ of the appropriate name.
1407 In our case, if ^an environment variable^a logical name^ called "mode"
1408 exist, its value will be taken into account.
1410 @item @b{External function second parameter}
1414 @cindex @code{external}
1415 We now need to get that value in the project. The general form is to use
1416 the predefined function @b{external} which returns the current value of
1417 the external. For instance, we could setup the object directory to point to
1418 either @file{obj/debug} or @file{obj/release} by changing our project to
1420 @smallexample @c projectfile
1422 for Object_Dir use "obj/" & external ("mode", "debug");
1428 The second parameter to @code{external} is optional, and is the default
1429 value to use if "mode" is not set from the command line or the environment.
1431 In order to set the switches according to the different scenarios, other
1432 constructs have to be introduced such as typed variables and case statements.
1434 @cindex typed variable
1435 @cindex case statement
1436 A @b{typed variable} is a variable that
1437 can take only a limited number of values, similar to an enumeration in Ada.
1438 Such a variable can then be used in a @b{case statement} and create conditional
1439 sections in the project. The following example shows how this can be done:
1441 @smallexample @c projectfile
1443 type Mode_Type is ("debug", "release"); -- all possible values
1444 Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1449 for Switches ("Ada") use ("-g");
1451 for Switches ("Ada") use ("-O2");
1458 The project has suddenly grown in size, but has become much more flexible.
1459 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1460 any other value is read from the environment, an error is reported and the
1461 project is considered as invalid.
1463 The @code{Mode} variable is initialized with an external value
1464 defaulting to @code{"debug"}. This default could be omitted and that would
1465 force the user to define the value. Finally, we can use a case statement to set the
1466 switches depending on the scenario the user has chosen.
1468 Most aspects of the projects can depend on scenarios. The notable exception
1469 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1471 Scenarios work the same way with @b{project hierarchies}: you can either
1472 duplicate a variable similar to @code{Mode} in each of the project (as long
1473 as the first argument to @code{external} is always the same and the type is
1474 the same), or simply set the variable in the @file{shared.gpr} project
1475 (@pxref{Sharing Between Projects}).
1477 @c ---------------------------------------------
1478 @node Library Projects
1479 @section Library Projects
1480 @c ---------------------------------------------
1483 So far, we have seen examples of projects that create executables. However,
1484 it is also possible to create libraries instead. A @b{library} is a specific
1485 type of subsystem where, for convenience, objects are grouped together
1486 using system-specific means such as archives or windows DLLs.
1488 Library projects provide a system- and language-independent way of building both @b{static}
1489 and @b{dynamic} libraries. They also support the concept of @b{standalone
1490 libraries} (SAL) which offers two significant properties: the elaboration
1491 (e.g. initialization) of the library is either automatic or very simple;
1493 implementation part of the library implies minimal post-compilation actions on
1494 the complete system and potentially no action at all for the rest of the
1495 system in the case of dynamic SALs.
1497 The GNAT Project Manager takes complete care of the library build, rebuild and
1498 installation tasks, including recompilation of the source files for which
1499 objects do not exist or are not up to date, assembly of the library archive, and
1500 installation of the library (i.e., copying associated source, object and
1501 @file{ALI} files to the specified location).
1504 * Building Libraries::
1505 * Using Library Projects::
1506 * Stand-alone Library Projects::
1507 * Installing a library with project files::
1510 @c ---------------------------------------------
1511 @node Building Libraries
1512 @subsection Building Libraries
1513 @c ---------------------------------------------
1516 Let's enhance our example and transform the @code{logging} subsystem into a
1517 library. In order to do so, a few changes need to be made to @file{logging.gpr}.
1518 A number of specific attributes needs to be defined: at least @code{Library_Name}
1519 and @code{Library_Dir}; in addition, a number of other attributes can be used
1520 to specify specific aspects of the library. For readability, it is also
1521 recommended (although not mandatory), to use the qualifier @code{library} in
1522 front of the @code{project} keyword.
1525 @item @b{Library_Name}:
1526 @cindex @code{Library_Name}
1527 This attribute is the name of the library to be built. There is no
1528 restriction on the name of a library imposed by the project manager;
1529 however, there may be system specific restrictions on the name.
1530 In general, it is recommended to stick to alphanumeric characters
1531 (and possibly underscores) to help portability.
1533 @item @b{Library_Dir}:
1534 @cindex @code{Library_Dir}
1535 This attribute is the path (absolute or relative) of the directory where
1536 the library is to be installed. In the process of building a library,
1537 the sources are compiled, the object files end up in the explicit or
1538 implicit @code{Object_Dir} directory. When all sources of a library
1539 are compiled, some of the compilation artifacts, including the library itself,
1540 are copied to the library_dir directory. This directory must exists and be
1541 writable. It must also be different from the object directory so that cleanup
1542 activities in the Library_Dir do not affect recompilation needs.
1546 Here is the new version of @file{logging.gpr} that makes it a library:
1548 @smallexample @c projectfile
1549 library project Logging is -- "library" is optional
1550 for Library_Name use "logging"; -- will create "liblogging.a" on Unix
1551 for Object_Dir use "obj";
1552 for Library_Dir use "lib"; -- different from object_dir
1557 Once the above two attributes are defined, the library project is valid and
1558 is enough for building a library with default characteristics.
1559 Other library-related attributes can be used to change the defaults:
1562 @item @b{Library_Kind}:
1563 @cindex @code{Library_Kind}
1564 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1565 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1566 which kind of library should be build (the default is to build a
1567 static library, that is an archive of object files that can potentially
1568 be linked into a static executable). When the library is set to be dynamic,
1569 a separate image is created that will be loaded independently, usually
1570 at the start of the main program execution. Support for dynamic libraries is
1571 very platform specific, for instance on Windows it takes the form of a DLL
1572 while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1573 @file{.so}. Library project files, on the other hand, can be written in
1574 a platform independent way so that the same project file can be used to build
1575 a library on different operating systems.
1577 If you need to build both a static and a dynamic library, it is recommended
1578 use two different object directories, since in some cases some extra code
1579 needs to be generated for the latter. For such cases, one can
1580 either define two different project files, or a single one which uses scenarios
1581 to indicate at the various kinds of library to be build and their
1582 corresponding object_dir.
1584 @cindex @code{Library_ALI_Dir}
1585 @item @b{Library_ALI_Dir}:
1586 This attribute may be specified to indicate the directory where the ALI
1587 files of the library are installed. By default, they are copied into the
1588 @code{Library_Dir} directory, but as for the executables where we have a
1589 separate @code{Exec_Dir} attribute, you might want to put them in a separate
1590 directory since there can be hundreds of them. The same restrictions as for
1591 the @code{Library_Dir} attribute apply.
1593 @cindex @code{Library_Version}
1594 @item @b{Library_Version}:
1595 This attribute is platform dependent, and has no effect on VMS and Windows.
1596 On Unix, it is used only for dynamic libraries as the internal
1597 name of the library (the @code{"soname"}). If the library file name (built
1598 from the @code{Library_Name}) is different from the @code{Library_Version},
1599 then the library file will be a symbolic link to the actual file whose name
1600 will be @code{Library_Version}. This follows the usual installation schemes
1601 for dynamic libraries on many Unix systems.
1603 @smallexample @c projectfile
1607 for Library_Dir use "lib";
1608 for Library_Name use "logging";
1609 for Library_Kind use "dynamic";
1610 for Library_Version use "liblogging.so." & Version;
1616 After the compilation, the directory @file{lib} will contain both a
1617 @file{libdummy.so.1} library and a symbolic link to it called
1620 @cindex @code{Library_GCC}
1621 @item @b{Library_GCC}:
1622 This attribute is the name of the tool to use instead of "gcc" to link shared
1623 libraries. A common use of this attribute is to define a wrapper script that
1624 accomplishes specific actions before calling gcc (which itself is calling the
1625 linker to build the library image).
1627 @item @b{Library_Options}:
1628 @cindex @code{Library_Options}
1629 This attribute may be used to specify additional switches (last switches)
1630 when linking a shared library.
1632 @item @b{Leading_Library_Options}:
1633 @cindex @code{Leading_Library_Options}
1634 This attribute, that is taken into account only by @command{gprbuild}, may be
1635 used to specified leading options (first switches) when linking a shared
1638 @cindex @code{Linker_Options}
1639 @item @b{Linker.Linker_Options}:
1640 This attribute specifies additional switches to be given to the linker when
1641 linking an executable. It is ignored when defined in the main project and
1642 taken into account in all other projects that are imported directly or
1643 indirectly. These switches complement the @code{Linker.Switches}
1644 defined in the main project. This is useful when a particular subsystem
1645 depends on an external library: adding this dependency as a
1646 @code{Linker_Options} in the project of the subsystem is more convenient than
1647 adding it to all the @code{Linker.Switches} of the main projects that depend
1648 upon this subsystem.
1652 @c ---------------------------------------------
1653 @node Using Library Projects
1654 @subsection Using Library Projects
1655 @c ---------------------------------------------
1658 When the builder detects that a project file is a library project file, it
1659 recompiles all sources of the project that need recompilation and rebuild the
1660 library if any of the sources have been recompiled. It then groups all object
1661 files into a single file, which is a shared or a static library. This library
1662 can later on be linked with multiple executables. Note that the use
1663 of shard libraries reduces the size of the final executable and can also reduce
1664 the memory footprint at execution time when the library is shared among several
1667 It is also possible to build @b{multi-language libraries}. When using
1668 @command{gprbuild} as a builder, multi-language library projects allow naturally
1669 the creation of multi-language libraries . @command{gnatmake}, does not try to
1670 compile non Ada sources. However, when the project is multi-language, it will
1671 automatically link all object files found in the object directory, whether or
1672 not they were compiled from an Ada source file. This specific behavior does not
1673 apply to Ada-only projects which only take into account the objects
1674 corresponding to the sources of the project.
1676 A non-library project can import a library project. When the builder is invoked
1677 on the former, the library of the latter is only rebuilt when absolutely
1678 necessary. For instance, if a unit of the
1679 library is not up-to-date but non of the executables need this unit, then the
1680 unit is not recompiled and the library is not reassembled.
1681 For instance, let's assume in our example that logging has the following
1682 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1683 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1684 @file{liblogging} will be rebuilt when compiling all the sources of
1685 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1686 include a @code{"with Log1"}.
1688 To ensure that all the sources in the @code{Logging} library are
1689 up to date, and that all the sources of @code{Build} are also up to date,
1690 the following two commands needs to be used:
1693 gnatmake -Plogging.gpr
1694 gnatmake -Pbuild.gpr
1698 All @file{ALI} files will also be copied from the object directory to the
1699 library directory. To build executables, @command{gnatmake} will use the
1700 library rather than the individual object files.
1703 Library projects can also be useful to describe a library that need to be used
1704 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1705 of the library sources are not available. Such library projects need simply to
1706 use the @code{Externally_Built} attribute as in the example below:
1708 @smallexample @c projectfile
1709 library project Extern_Lib is
1710 for Languages use ("Ada", "C");
1711 for Source_Dirs use ("lib_src");
1712 for Library_Dir use "lib2";
1713 for Library_Kind use "dynamic";
1714 for Library_Name use "l2";
1715 for Externally_Built use "true"; -- <<<<
1720 In the case of externally built libraries, the @code{Object_Dir}
1721 attribute does not need to be specified because it will never be
1724 The main effect of using such an externally built library project is mostly to
1725 affect the linker command in order to reference the desired library. It can
1726 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1727 in the project corresponding to the subsystem needing this external library.
1728 This latter method is more straightforward in simple cases but when several
1729 subsystems depend upon the same external library, finding the proper place
1730 for the @code{Linker.Linker_Options} might not be easy and if it is
1731 not placed properly, the final link command is likely to present ordering issues.
1732 In such a situation, it is better to use the externally built library project
1733 so that all other subsystems depending on it can declare this dependency thanks
1734 to a project @code{with} clause, which in turn will trigger the builder to find
1735 the proper order of libraries in the final link command.
1738 @c ---------------------------------------------
1739 @node Stand-alone Library Projects
1740 @subsection Stand-alone Library Projects
1741 @c ---------------------------------------------
1744 @cindex standalone libraries
1745 A @b{stand-alone library} is a library that contains the necessary code to
1746 elaborate the Ada units that are included in the library. A stand-alone
1747 library is a convenient way to add an Ada subsystem to a more global system
1748 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1749 transparent. However, stand-alone libraries are also useful when the main is in
1750 Ada: they provide a means for minimizing relinking & redeployment of complex
1751 systems when localized changes are made.
1753 The most prominent characteristic of a stand-alone library is that it offers a
1754 distinction between interface units and implementation units. Only the former
1755 are visible to units outside the library. A stand-alone library project is thus
1756 characterised by a third attribute, @b{Library_Interface}, in addition to the
1757 two attributes that make a project a Library Project (@code{Library_Name} and
1758 @code{Library_Dir}).
1761 @item @b{Library_Interface}:
1762 @cindex @code{Library_Interface}
1763 This attribute defines an explicit subset of the units of the project.
1764 Projects importing this library project may only "with" units whose sources
1765 are listed in the @code{Library_Interface}. Other sources are considered
1766 implementation units.
1768 @smallexample @c projectfile
1770 for Library_Dir use "lib";
1771 for Library_Name use "loggin";
1772 for Library_Interface use ("lib1", "lib2"); -- unit names
1778 In order to include the elaboration code in the stand-alone library, the binder
1779 is invoked on the closure of the library units creating a package whose name
1780 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1781 This binder-generated package includes @b{initialization} and @b{finalization}
1782 procedures whose names depend on the library name (@code{logginginit} and
1783 @code{loggingfinal} in the example). The object corresponding to this package is
1784 included in the library.
1787 @item @b{Library_Auto_Init}:
1788 @cindex @code{Library_Auto_Init}
1789 A dynamic stand-alone Library is automatically initialized
1790 if automatic initialization of Stand-alone Libraries is supported on the
1791 platform and if attribute @b{Library_Auto_Init} is not specified or
1792 is specified with the value "true". A static Stand-alone Library is never
1793 automatically initialized. Specifying "false" for this attribute
1794 prevent automatic initialization.
1796 When a non-automatically initialized stand-alone library is used in an
1797 executable, its initialization procedure must be called before any service of
1798 the library is used. When the main subprogram is in Ada, it may mean that the
1799 initialization procedure has to be called during elaboration of another
1802 @item @b{Library_Dir}:
1803 @cindex @code{Library_Dir}
1804 For a stand-alone library, only the @file{ALI} files of the interface units
1805 (those that are listed in attribute @code{Library_Interface}) are copied to
1806 the library directory. As a consequence, only the interface units may be
1807 imported from Ada units outside of the library. If other units are imported,
1808 the binding phase will fail.
1810 @item @b{Binder.Default_Switches}:
1811 When a stand-alone library is bound, the switches that are specified in
1812 the attribute @b{Binder.Default_Switches ("Ada")} are
1813 used in the call to @command{gnatbind}.
1815 @item @b{Library_Src_Dir}:
1816 @cindex @code{Library_Src_Dir}
1817 This attribute defines the location (absolute or relative to the project
1818 directory) where the sources of the interface units are copied at
1820 These sources includes the specs of the interface units along with the closure
1821 of sources necessary to compile them successfully. That may include bodies and
1822 subunits, when pragmas @code{Inline} are used, or when there is a generic
1823 units in the spec. This directory cannot point to the object directory or
1824 one of the source directories, but it can point to the library directory,
1825 which is the default value for this attribute.
1827 @item @b{Library_Symbol_Policy}:
1828 @cindex @code{Library_Symbol_Policy}
1829 This attribute controls the export of symbols and, on some platforms (like
1830 VMS) that have the notions of major and minor IDs built in the library
1831 files, it controls the setting of these IDs. It is not supported on all
1832 platforms (where it will just have no effect). It may have one of the
1836 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1837 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1838 is not defined, then it is equivalent to policy "autonomous". If there
1839 are exported symbols in the reference symbol file that are not in the
1840 object files of the interfaces, the major ID of the library is increased.
1841 If there are symbols in the object files of the interfaces that are not
1842 in the reference symbol file, these symbols are put at the end of the list
1843 in the newly created symbol file and the minor ID is increased.
1844 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1845 defined. The library will fail to build if the exported symbols in the
1846 object files of the interfaces do not match exactly the symbol in the
1848 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1849 The library will fail to build if there are symbols in the symbol file that
1850 are not in the exported symbols of the object files of the interfaces.
1851 Additional symbols in the object files are not added to the symbol file.
1852 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1853 must designate an existing file in the object directory. This symbol file
1854 is passed directly to the underlying linker without any symbol processing.
1858 @item @b{Library_Reference_Symbol_File}
1859 @cindex @code{Library_Reference_Symbol_File}
1860 This attribute may define the path name of a reference symbol file that is
1861 read when the symbol policy is either "compliant" or "controlled", on
1862 platforms that support symbol control, such as VMS, when building a
1863 stand-alone library. The path may be an absolute path or a path relative
1864 to the project directory.
1866 @item @b{Library_Symbol_File}
1867 @cindex @code{Library_Symbol_File}
1868 This attribute may define the name of the symbol file to be created when
1869 building a stand-alone library when the symbol policy is either "compliant",
1870 "controlled" or "restricted", on platforms that support symbol control,
1871 such as VMS. When symbol policy is "direct", then a file with this name
1872 must exist in the object directory.
1876 @c ---------------------------------------------
1877 @node Installing a library with project files
1878 @subsection Installing a library with project files
1879 @c ---------------------------------------------
1882 When using project files, library installation is part of the library build
1883 process. Thus no further action is needed in order to make use of the
1884 libraries that are built as part of the general application build. A usable
1885 version of the library is installed in the directory specified by the
1886 @code{Library_Dir} attribute of the library project file.
1888 You may want to install a library in a context different from where the library
1889 is built. This situation arises with third party suppliers, who may want
1890 to distribute a library in binary form where the user is not expected to be
1891 able to recompile the library. The simplest option in this case is to provide
1892 a project file slightly different from the one used to build the library, by
1893 using the @code{externally_built} attribute. @ref{Using Library Projects}
1895 @c ---------------------------------------------
1896 @node Project Extension
1897 @section Project Extension
1898 @c ---------------------------------------------
1901 During development of a large system, it is sometimes necessary to use
1902 modified versions of some of the source files, without changing the original
1903 sources. This can be achieved through the @b{project extension} facility.
1905 Suppose for instance that our example @code{Build} project is build every night
1906 for the whole team, in some shared directory. A developer usually need to work
1907 on a small part of the system, and might not want to have a copy of all the
1908 sources and all the object files (mostly because that would require too much
1909 disk space, time to recompile everything). He prefers to be able to override
1910 some of the source files in his directory, while taking advantage of all the
1911 object files generated at night.
1913 Another example can be taken from large software systems, where it is common to have
1914 multiple implementations of a common interface; in Ada terms, multiple
1915 versions of a package body for the same spec. For example, one implementation
1916 might be safe for use in tasking programs, while another might only be used
1917 in sequential applications. This can be modeled in GNAT using the concept
1918 of @emph{project extension}. If one project (the ``child'') @emph{extends}
1919 another project (the ``parent'') then by default all source files of the
1920 parent project are inherited by the child, but the child project can
1921 override any of the parent's source files with new versions, and can also
1922 add new files or remove unnecessary ones.
1923 This facility is the project analog of a type extension in
1924 object-oriented programming. Project hierarchies are permitted (an extending
1925 project may itself be extended), and a project that
1926 extends a project can also import other projects.
1928 A third example is that of using project extensions to provide different
1929 versions of the same system. For instance, assume that a @code{Common}
1930 project is used by two development branches. One of the branches has now
1931 been frozen, and no further change can be done to it or to @code{Common}.
1932 However, the other development branch still needs evolution of @code{Common}.
1933 Project extensions provide a flexible solution to create a new version
1934 of a subsystem while sharing and reusing as much as possible from the original
1937 A project extension inherits implicitly all the sources and objects from the
1938 project it extends. It is possible to create a new version of some of the
1939 sources in one of the additional source dirs of the extending project. Those new
1940 versions hide the original versions. Adding new sources or removing existing
1941 ones is also possible. Here is an example on how to extend the project
1942 @code{Build} from previous examples:
1944 @smallexample @c projectfile
1945 project Work extends "../bld/build.gpr" is
1950 The project after @b{extends} is the one being extended. As usual, it can be
1951 specified using an absolute path, or a path relative to any of the directories
1952 in the project path (@pxref{Project Dependencies}). This project does not
1953 specify source or object directories, so the default value for these attribute
1954 will be used that is to say the current directory (where project @code{Work} is
1955 placed). We can already compile that project with
1962 If no sources have been placed in the current directory, this command
1963 won't do anything, since this project does not change the
1964 sources it inherited from @code{Build}, therefore all the object files
1965 in @code{Build} and its dependencies are still valid and are reused
1968 Suppose we now want to supply an alternate version of @file{pack.adb}
1969 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
1970 We can create the new file Work's current directory (likely
1971 by copying the one from the @code{Build} project and making changes to
1972 it. If new packages are needed at the same time, we simply create
1973 new files in the source directory of the extending project.
1975 When we recompile, @command{gnatmake} will now automatically recompile
1976 this file (thus creating @file{pack.o} in the current directory) and
1977 any file that depends on it (thus creating @file{proc.o}). Finally, the
1978 executable is also linked locally.
1980 Note that we could have obtained the desired behavior using project import
1981 rather than project inheritance. A @code{base} project would contain the
1982 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
1983 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
1984 cannot contain the original version of @file{pack.adb} otherwise there would be
1985 2 versions of the same unit in the closure of the project and this is not
1986 allowed. Generally speaking, it is not recommended to put the spec and the
1987 body of a unit in different projects since this affects their autonomy and
1990 In a project file that extends another project, it is possible to
1991 indicate that an inherited source is @b{not part} of the sources of the
1992 extending project. This is necessary sometimes when a package spec has
1993 been overridden and no longer requires a body: in this case, it is
1994 necessary to indicate that the inherited body is not part of the sources
1995 of the project, otherwise there will be a compilation error
1996 when compiling the spec.
1998 @cindex @code{Excluded_Source_Files}
1999 @cindex @code{Excluded_Source_List_File}
2000 For that purpose, the attribute @b{Excluded_Source_Files} is used.
2001 Its value is a list of file names.
2002 It is also possible to use attribute @code{Excluded_Source_List_File}.
2003 Its value is the path of a text file containing one file name per
2006 @smallexample @c @projectfile
2007 project Work extends "../bld/build.gpr" is
2008 for Source_Files use ("pack.ads");
2009 -- New spec of Pkg does not need a completion
2010 for Excluded_Source_Files use ("pack.adb");
2015 An extending project retains all the switches specified in the
2019 * Project Hierarchy Extension::
2022 @c ---------------------------------------------
2023 @node Project Hierarchy Extension
2024 @subsection Project Hierarchy Extension
2025 @c ---------------------------------------------
2028 One of the fundamental restrictions in project extension is the following:
2029 @b{A project is not allowed to import directly or indirectly at the same time an
2030 extending project and one of its ancestors}.
2032 By means of example, consider the following hierarchy of projects.
2035 a.gpr contains package A1
2036 b.gpr, imports a.gpr and contains B1, which depends on A1
2037 c.gpr, imports b.gpr and contains C1, which depends on B1
2041 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2042 create several extending projects:
2045 a_ext.gpr which extends a.gpr, and overrides A1
2046 b_ext.gpr which extends b.gpr and imports a_ext.gpr
2047 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2051 @smallexample @c projectfile
2052 project A_Ext extends "a.gpr" is
2053 for Source_Files use ("a1.adb", "a1.ads");
2057 project B_Ext extends "b.gpr" is
2061 project C_Ext extends "c.gpr" is
2062 for Source_Files use ("c1.adb");
2067 The extension @file{b_ext.gpr} is required, even though we are not overriding
2068 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2069 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2072 When extending a large system spanning multiple projects, it is often
2073 inconvenient to extend every project in the hierarchy that is impacted by a
2074 small change introduced in a low layer. In such cases, it is possible to create
2075 an @b{implicit extension} of entire hierarchy using @b{extends all}
2078 When the project is extended using @code{extends all} inheritance, all projects
2079 that are imported by it, both directly and indirectly, are considered virtually
2080 extended. That is, the project manager creates implicit projects
2081 that extend every project in the hierarchy; all these implicit projects do not
2082 control sources on their own and use the object directory of
2083 the "extending all" project.
2085 It is possible to explicitly extend one or more projects in the hierarchy
2086 in order to modify the sources. These extending projects must be imported by
2087 the "extending all" project, which will replace the corresponding virtual
2088 projects with the explicit ones.
2090 When building such a project hierarchy extension, the project manager will
2091 ensure that both modified sources and sources in implicit extending projects
2092 that depend on them, are recompiled.
2094 Thus, in our example we could create the following projects instead:
2097 a_ext.gpr, extends a.gpr and overrides A1
2098 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2103 @smallexample @c projectfile
2104 project A_Ext extends "a.gpr" is
2105 for Source_Files use ("a1.adb", "a1.ads");
2109 project C_Ext extends all "c.gpr" is
2110 for Source_Files use ("c1.adb");
2115 When building project @file{c_ext.gpr}, the entire modified project space is
2116 considered for recompilation, including the sources of @file{b.gpr} that are
2117 impacted by the changes in @code{A1} and @code{C1}.
2119 @c ---------------------------------------------
2120 @node Aggregate Projects
2121 @section Aggregate Projects
2122 @c ---------------------------------------------
2126 Aggregate projects are an extension of the project paradigm, and are
2127 meant to solve a few specific use cases that cannot be solved directly
2128 using standard projects. This section will go over a few of these use
2129 cases to try and explain what you can use aggregate projects for.
2131 @subsection Building all main units from a single project tree
2133 Most often, an application is organized into modules and submodules,
2134 which are very conveniently represented as a project tree or graph
2135 (the root project A @code{with}s the projects for each modules (say B and C),
2136 which in turn @code{with} projects for submodules.
2138 Very often, modules will build their own executables (for testing
2139 purposes for instance), or libraries (for easier reuse in various
2142 However, if you build your project through gnatmake or gprbuild, using
2149 this will only rebuild the main units of project A, not those of the
2150 imported projects B and C. Therefore you have to spawn several
2151 gnatmake commands, one per project, to build all executables.
2152 This is a little inconvenient, but more importantly is inefficient
2153 (since gnatmake needs to do duplicate work to ensure that sources are
2154 up-to-date, and cannot easily compile things in parallel when using
2157 Also libraries are always rebuild when building a project.
2159 You could therefore define an aggregate project Agg that groups A, B
2160 and C. Then, when you build with
2166 this will build all main units from A, B and C.
2168 @smallexample @c projectfile
2169 aggregate project Agg is
2170 for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2174 If B or C do not define any main unit (through their Main
2175 attribute), all their sources are build. When you do not group them
2176 in the aggregate project, only those sources that are needed by A
2179 If you add a main unit to a project P not already explicitly referenced in the
2180 aggregate project, you will need to add "p.gpr" in the list of project
2181 files for the aggregate project, or the main unit will not be built when
2182 building the aggregate project.
2184 @subsection Building a set of projects with a single command
2186 One other case is when you have multiple applications and libraries
2187 that are build independently from each other (but they can be build in
2188 parallel). For instance, you have a project tree rooted at A, and
2189 another one (which might share some subprojects) rooted at B.
2191 Using only gprbuild, you could do
2198 to build both. But again, gprbuild has to do some duplicate work for
2199 those files that are shared between the two, and cannot truly build
2200 things in parallel efficiently.
2202 If the two projects are really independent, share no sources other
2203 than through a common subproject, and have no source files with a
2204 common basename, you could create a project C that imports A and
2205 B. But these restrictions are often too strong, and one has to build
2206 them independently. An aggregate project does not have these
2207 limitations, and can aggregate two project trees that have common
2211 Aggregate projects can group projects with duplicate file names
2214 This scenario is particularly useful in environment like VxWork 653
2215 where the applications running in the multiple partitions can be build
2216 in parallel through a single gprbuild command. This also works nicely
2220 Aggregate projects can be used to build multiple partitions
2223 @subsection Define a build environment
2225 The environment variables at the time you launch gprbuild or gprbuild
2226 will influence the view these tools have of the project (PATH to find
2227 the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
2228 projects, environment variables that are referenced in project files
2229 through the "external" statement,...). Several command line switches
2230 can be used to override those (-X or -aP), but on some systems and
2231 with some projects, this might make the command line too long, and on
2232 all systems often make it hard to read.
2234 An aggregate project can be used to set the environment for all
2235 projects build through that aggregate. One of the nice aspects is that
2236 you can put the aggregate project under configuration management, and
2237 make sure all your user have a consistent environment when
2238 building. The syntax looks like
2240 @smallexample @c projectfile
2241 aggregate project Agg is
2242 for Project_Files use ("A.gpr", "B.gpr");
2243 for Project_Path use ("../dir1", "../dir1/dir2");
2244 for External ("BUILD") use "PRODUCTION";
2247 for Switches ("Ada") use ("-q");
2252 One of the often requested features in projects is to be able to
2253 reference external variables in @code{with} statements, as in
2255 @smallexample @c projectfile
2256 with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
2257 project MyProject is
2262 For various reasons, this isn't authorized. But using aggregate
2263 projects provide an elegant solution. For instance, you could
2264 use a project file like:
2266 @smallexample @c projectfile
2267 aggregate project Agg is
2268 for Project_Path use (external("SETUP") % "path");
2269 for Project_Files use ("myproject.gpr");
2273 with "prj.gpr"; -- searched on Agg'Project_Path
2274 project MyProject is
2279 @subsection Performance improvements in builder
2281 The loading of aggregate projects is optimized in gprbuild and
2282 gnatmake, so that all files are searched for only once on the disk
2283 (thus reducing the number of system calls and contributing to faster
2284 compilation times especially on systems with sources on remote
2285 servers). As part of the loading, gprbuild and gnatmake compute how
2286 and where a source file should be compiled, and even if it is found
2287 several times in the aggregated projects it will be compiled only
2290 Since there is no ambiguity as to which switches should be used, files
2291 can be compiled in parallel (through the usual -j switch) and this can
2292 be done while maximizing the use of CPUs (compared to launching
2293 multiple gprbuild and gnatmake commands in parallel).
2295 @subsection Syntax of aggregate projects
2297 An aggregate project follows the general syntax of project files. The
2298 recommended extension is still @file{.gpr}. However, a special
2299 @code{aggregate} qualifier must be put before the keyword
2302 An aggregate project cannot @code{with} any other project (standard or
2303 aggregate), except an abstract project which can be used to share
2304 attribute values. Building other aggregate projects from an aggregate
2305 project is done through the Project_Files attribute (see below).
2307 An aggregate project does not have any source files directly (only
2308 through other standard projects). Therefore a number of the standard
2309 attributes and packages are forbidden in an aggregate project. Here is the
2310 (non exhaustive) list:
2314 @item Source_files, Source_List_File and other attributes dealing with
2316 @item Source_Dirs, Exec_Dir and Object_Dir
2317 @item Library_Dir, Library_Name and other library-related attributes
2320 @item Externally_Built
2321 @item Inherit_Source_Path
2322 @item Excluded_Source_Dirs
2323 @item Locally_Removed_Files
2324 @item Excluded_Source_Fies
2325 @item Excluded_Source_List_File
2329 The only package that is authorized (albeit optional) is
2330 Builder. Other packages (in particular Compiler, Binder and Linker)
2331 are forbidden. It is an error to have any of these
2332 (and such an error prevents the proper loading of the aggregate
2335 Three new attributes have been created, which can only be used in the
2336 context of aggregate projects:
2339 @item @b{Project_Files}:
2340 @cindex @code{Project_Files}
2342 This attribute is compulsory (or else we are not aggregating any project,
2343 and thus not doing anything). It specifies a list of @file{.gpr} files
2344 that are grouped in the aggregate. The list may be empty. The project
2345 files can be either other aggregate projects, or standard projects. When
2346 grouping standard projects, you can have both the root of a project tree
2347 (and you do not need to specify all its imported projects), and any project
2350 Basically, the idea is to specify all those projects that have
2351 main units you want to build and link, or libraries you want to
2352 build. You can even specify projects that do not use the Main
2353 attribute nor the @code{Library_*} attributes, and the result will be to
2354 build all their source files (not just the ones needed by other
2357 The file can include paths (absolute or relative). Paths are
2358 relative to the location of the aggregate project file itself (if
2359 you use a base name, we expect to find the .gpr file in the same
2360 directory as the aggregate project file). The extension @file{.gpr} is
2361 mandatory, since this attribute contains file names, not project names.
2363 Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
2364 latter indicates that any subdirectory (recursively) will be
2365 searched for matching files. The latter (@code{"**"}) can only occur at the
2366 last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
2367 not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
2368 to starting with @code{"./**"}.
2370 For now, the pattern @code{"*"} is only allowed in the filename part, not
2371 in the directory part. This is mostly for efficiency reasons to limit the
2372 number of system calls that are needed.
2374 Here are a few valid examples:
2376 @smallexample @c projectfile
2377 for Project_Files use ("a.gpr", "subdir/b.gpr");
2378 -- two specific projects relative to the directory of agg.gpr
2380 for Project_Files use ("**/*.gpr");
2381 -- all projects recursively
2384 @item @b{Project_Path}:
2385 @cindex @code{Project_Path}
2387 This attribute can be used to specify a list of directories in
2388 which to look for project files in @code{with} statements.
2390 When you specify a project in Project_Files
2391 say @code{"x/y/a.gpr"}), and this projects imports a project "b.gpr", only
2392 b.gpr is searched in the project path. a.gpr must be exactly at
2393 <dir of the aggregate>/x/y/a.gpr.
2395 This attribute, however, does not affect the search for the aggregated
2396 project files specified with @code{Project_Files}.
2398 Each aggregate project has its own (that is if agg1.gpr includes
2399 agg2.gpr, they can potentially both have a different project path).
2400 This project path is defined as the concatenation, in that order, of
2401 the current directory, followed by the command line -aP switches,
2402 then the directories from the Project_Path attribute, then the
2403 directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH env.
2404 variables, and finally the predefined directories.
2406 In the example above, agg2.gpr's project path is not influenced by
2407 the attribute agg1'Project_Path, nor is agg1 influenced by
2410 This can potentially lead to errors. In the following example:
2413 +---------------+ +----------------+
2414 | Agg1.gpr |-=--includes--=-->| Agg2.gpr |
2415 | 'project_path| | 'project_path |
2417 +---------------+ +----------------+
2422 +-------+ +---------+
2423 | P.gpr |<---------- withs --------| Q.gpr |
2424 +-------+---------\ +---------+
2429 +-------+ +---------+
2430 | R.gpr | | R'.gpr |
2431 +-------+ +---------+
2434 When looking for p.gpr, both aggregates find the same physical file on
2435 the disk. However, it might happen that with their different project
2436 paths, both aggregate projects would in fact find a different r.gpr.
2437 Since we have a common project (p.gpr) "with"ing two different r.gpr,
2438 this will be reported as an error by the builder.
2440 Directories are relative to the location of the aggregate project file.
2442 Here are a few valid examples:
2444 @smallexample @c projectfile
2445 for Project_Path use ("/usr/local/gpr", "gpr/");
2449 @cindex @code{External}
2451 This attribute can be used to set the value of environment
2452 variables as retrieved through the @code{external} statement
2453 in projects. It does not affect the environment variables
2454 themselves (so for instance you cannot use it to change the value
2455 of your PATH as seen from the spawned compiler).
2457 This attribute affects the external values as seen in the rest of
2458 the aggreate projects, and in the aggregated projects.
2460 The exact value of external a variable comes from one of three
2461 sources (each level overrides the previous levels):
2464 @item An External attribute in aggregate project, for instance
2465 @code{for External ("BUILD_MODE") use "DEBUG"};
2467 @item Environment variables
2469 These override the value given by the attribute, so that
2470 users can override the value set in the (presumably shared
2471 with others in his team) aggregate project.
2473 @item The -X command line switch to gprbuild and gnatmake
2475 This always takes precedence.
2479 This attribute is only taken into account in the main aggregate
2480 project (i.e. the one specified on the command line to gprbuild or
2481 natmake), and ignored in other aggregate projects. It is invalid
2482 in standard projects.
2483 The goal is to have a consistent value in all
2484 projects that are build through the aggregate, which would not
2485 be the case in the diamond case: A groups the aggregate
2486 projects B and C, which both (either directly or indirectly)
2487 build the project P. If B and C could set different values for
2488 the environment variables, we would have two different views of
2489 P, which in particular might impact the list of source files in P.
2493 @subsection package Builder in aggregate projects
2495 As we mentioned before, only the package Builder can be specified in
2496 an aggregate project. In this package, only the following attributes
2501 @cindex @code{Switches}
2502 This attribute gives the list of switches to use for the builder
2503 (gprbuild or gnatmake), depending on the language of the main file.
2506 @smallexample @c projectfile
2507 for Switches ("Ada") use ("-d", "-p");
2508 for Switches ("C") use ("-p");
2511 These switches are only read from the main aggregate project (the
2512 one passed on the command line), and ignored in all other aggregate
2513 projects or projects.
2515 It can only contain builder switches, not compiler switches.
2517 @item @b{Global_Compilation_Switches}
2518 @cindex @code{Global_Compilation_Switches}
2520 This attribute gives the list of compiler switches for the various
2521 languages. For instance,
2523 @smallexample @c projectfile
2524 for Global_Compilation_Switches ("Ada") use ("-O1", "-g");
2525 for Global_Compilation_Switches ("C") use ("-O2");
2528 This attribute is only taken into account in the aggregate project
2529 specified on the command line, not in other aggregate projects.
2531 In the projects grouped by that aggregate, the attribute
2532 Builder.Global_Compilation_Switches is also ignored. However, the
2533 attribute Compiler.Default_Switches will be taken into account (but
2534 that of the aggregate have higher priority). The attribute
2535 Compiler.Switches is also taken into account and can be used to
2536 override the switches for a specific file. As a result, it always
2539 The rules are meant to avoid ambiguities when compiling. For
2540 instance, aggregate project Agg groups the projects A and B, that
2541 both depend on C. Here is an extra for all of these projects:
2543 @smallexample @c projectfile
2544 aggregate project Agg is
2545 for Project_Files use ("a.gpr", "b.gpr");
2547 for Global_Compilation_Switches ("Ada") use ("-O2");
2554 for Global_Compilation_Switches ("Ada") use ("-O1");
2559 for Default_Switches ("Ada") use ("-O1", "-g");
2560 for Switches ("a_file1.adb") use ("-O0");
2567 for Default_Switches ("Ada") use ("-O0");
2573 for Default_Switches ("Ada") use ("-O3, "-gnatn");
2574 for Switches ("c_file1.adb") use ("-O0", "-g");
2579 then the following switches are used:
2582 @item all files from project A except a_file1.adb are compiled
2583 with "-O2 -g", since the aggregate project has priority.
2584 @item the file a_file1.adb is compiled with
2585 "-O0", since the Compiler.Switches has priority
2586 @item all files from project B are compiled with
2587 "-O2", since the aggregate project has priority
2588 @item all files from C are compiled with "-O2 -gnatn", except for
2589 c_file1.adb which is compiled with "-O0 -g"
2592 Even though C is seen through two paths (through A and through
2593 B), the switches used by the compiler are unambiguous.
2595 @item @b{Global_Configuration_Pragmas}
2596 @cindex @code{Global_Configuration_Pragmas}
2598 This attribute can be used to specify a file containing
2599 configuration pragmas, to be passed to the compiler. Since we
2600 ignore the package Builder in other aggregate projects and projects,
2601 only those pragmas defined in the main aggregate project will be
2604 Projects can locally add to those by using the
2605 @code{Compiler.Local_Configuration_Pragmas} attribute if they need.
2609 For projects that are build through the aggregate, the package Builder
2610 is ignored, except for the Executable attribute which specifies the
2611 name of the executables resulting from the link of the main units, and
2612 for the Executable_Suffix.
2614 @c ---------------------------------------------
2615 @node Project File Reference
2616 @section Project File Reference
2617 @c ---------------------------------------------
2620 This section describes the syntactic structure of project files, the various
2621 constructs that can be used. Finally, it ends with a summary of all available
2625 * Project Declaration::
2626 * Qualified Projects::
2631 * Typed String Declaration::
2637 @c ---------------------------------------------
2638 @node Project Declaration
2639 @subsection Project Declaration
2640 @c ---------------------------------------------
2643 Project files have an Ada-like syntax. The minimal project file is:
2645 @smallexample @c projectfile
2653 The identifier @code{Empty} is the name of the project.
2654 This project name must be present after the reserved
2655 word @code{end} at the end of the project file, followed by a semi-colon.
2657 @b{Identifiers} (i.e.@: the user-defined names such as project or variable names)
2658 have the same syntax as Ada identifiers: they must start with a letter,
2659 and be followed by zero or more letters, digits or underscore characters;
2660 it is also illegal to have two underscores next to each other. Identifiers
2661 are always case-insensitive ("Name" is the same as "name").
2664 simple_name ::= identifier
2665 name ::= simple_name @{ . simple_name @}
2669 @b{Strings} are used for values of attributes or as indexes for these
2670 attributes. They are in general case sensitive, except when noted
2671 otherwise (in particular, strings representing file names will be case
2672 insensitive on some systems, so that "file.adb" and "File.adb" both
2673 represent the same file).
2675 @b{Reserved words} are the same as for standard Ada 95, and cannot
2676 be used for identifiers. In particular, the following words are currently
2677 used in project files, but others could be added later on. In bold are the
2678 extra reserved words in project files: @code{all, at, case, end, for, is,
2679 limited, null, others, package, renames, type, use, when, with, @b{extends},
2680 @b{external}, @b{project}}.
2682 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2683 hyphens through the end of the line.
2685 A project may be an @b{independent project}, entirely defined by a single
2686 project file. Any source file in an independent project depends only
2687 on the predefined library and other source files in the same project.
2688 But a project may also depend on other projects, either by importing them
2689 through @b{with clauses}, or by @b{extending} at most one other project. Both
2690 types of dependency can be used in the same project.
2692 A path name denotes a project file. It can be absolute or relative.
2693 An absolute path name includes a sequence of directories, in the syntax of
2694 the host operating system, that identifies uniquely the project file in the
2695 file system. A relative path name identifies the project file, relative
2696 to the directory that contains the current project, or relative to a
2697 directory listed in the environment variables ADA_PROJECT_PATH and
2698 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2699 operating system are case sensitive. As a special case, the directory
2700 separator can always be "/" even on Windows systems, so that project files
2701 can be made portable across architectures.
2702 The syntax of the environment variable ADA_PROJECT_PATH and
2703 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2704 semicolons on Windows.
2706 A given project name can appear only once in a context clause.
2708 It is illegal for a project imported by a context clause to refer, directly
2709 or indirectly, to the project in which this context clause appears (the
2710 dependency graph cannot contain cycles), except when one of the with clause
2711 in the cycle is a @b{limited with}.
2712 @c ??? Need more details here
2714 @smallexample @c projectfile
2715 with "other_project.gpr";
2716 project My_Project extends "extended.gpr" is
2721 These dependencies form a @b{directed graph}, potentially cyclic when using
2722 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
2725 A project's @b{immediate sources} are the source files directly defined by
2726 that project, either implicitly by residing in the project source directories,
2727 or explicitly through any of the source-related attributes.
2728 More generally, a project sources are the immediate sources of the project
2729 together with the immediate sources (unless overridden) of any
2730 project on which it depends directly or indirectly.
2732 A @b{project hierarchy} can be created, where projects are children of
2733 other projects. The name of such a child project must be @code{Parent.Child},
2734 where @code{Parent} is the name of the parent project. In particular, this
2735 makes all @code{with} clauses of the parent project automatically visible
2736 in the child project.
2739 project ::= context_clause project_declaration
2741 context_clause ::= @{with_clause@}
2742 with_clause ::= @i{with} path_name @{ , path_name @} ;
2743 path_name ::= string_literal
2745 project_declaration ::= simple_project_declaration | project_extension
2746 simple_project_declaration ::=
2747 @i{project} @i{<project_>}name @i{is}
2748 @{declarative_item@}
2749 @i{end} <project_>simple_name;
2752 @c ---------------------------------------------
2753 @node Qualified Projects
2754 @subsection Qualified Projects
2755 @c ---------------------------------------------
2758 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
2759 is identifiers or reserved words, to qualify the project.
2760 The current list of qualifiers is:
2763 @item @b{abstract}: qualifies a project with no sources. Such a
2764 project must either have no declaration of attributes @code{Source_Dirs},
2765 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
2766 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
2767 as empty. If it extends another project, the project it extends must also be a
2768 qualified abstract project.
2769 @item @b{standard}: a standard project is a non library project with sources.
2770 This is the default (implicit) qualifier.
2771 @item @b{aggregate}: for future extension
2772 @item @b{aggregate library}: for future extension
2773 @item @b{library}: a library project must declare both attributes
2774 @code{Library_Name} and @code{Library_Dir}.
2775 @item @b{configuration}: a configuration project cannot be in a project tree.
2776 It describes compilers and other tools to @code{gprbuild}.
2780 @c ---------------------------------------------
2782 @subsection Declarations
2783 @c ---------------------------------------------
2786 Declarations introduce new entities that denote types, variables, attributes,
2787 and packages. Some declarations can only appear immediately within a project
2788 declaration. Others can appear within a project or within a package.
2791 declarative_item ::= simple_declarative_item
2792 | typed_string_declaration
2793 | package_declaration
2795 simple_declarative_item ::= variable_declaration
2796 | typed_variable_declaration
2797 | attribute_declaration
2801 empty_declaration ::= @i{null} ;
2805 An empty declaration is allowed anywhere a declaration is allowed. It has
2808 @c ---------------------------------------------
2810 @subsection Packages
2811 @c ---------------------------------------------
2814 A project file may contain @b{packages}, that group attributes (typically
2815 all the attributes that are used by one of the GNAT tools).
2817 A package with a given name may only appear once in a project file.
2818 The following packages are currently supported in project files
2819 (See @pxref{Attributes} for the list of attributes that each can contain).
2823 This package specifies characteristics useful when invoking the binder either
2824 directly via the @command{gnat} driver or when using a builder such as
2825 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
2827 This package specifies the compilation options used when building an
2828 executable or a library for a project. Most of the options should be
2829 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
2830 but there are some general options that should be defined in this
2831 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
2834 This package specifies the options used when calling the checking tool
2835 @command{gnatcheck} via the @command{gnat} driver. Its attribute
2836 @b{Default_Switches} has the same semantics as for the package
2837 @code{Builder}. The first string should always be @code{-rules} to specify
2838 that all the other options belong to the @code{-rules} section of the
2839 parameters to @command{gnatcheck}.
2841 This package specifies the compilation options used by the compiler for
2842 each languages. @xref{Tools Options in Project Files}.
2843 @item Cross_Reference
2844 This package specifies the options used when calling the library tool
2845 @command{gnatxref} via the @command{gnat} driver. Its attributes
2846 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2847 package @code{Builder}.
2849 This package specifies the options used when calling the tool
2850 @command{gnatelim} via the @command{gnat} driver. Its attributes
2851 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2852 package @code{Builder}.
2854 This package specifies the options used when calling the search tool
2855 @command{gnatfind} via the @command{gnat} driver. Its attributes
2856 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2857 package @code{Builder}.
2859 This package the options to use when invoking @command{gnatls} via the
2860 @command{gnat} driver.
2862 This package specifies the options used when calling the tool
2863 @command{gnatstub} via the @command{gnat} driver. Its attributes
2864 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2865 package @code{Builder}.
2867 This package specifies the options used when starting an integrated
2868 development environment, for instance @command{GPS} or @command{Gnatbench}.
2869 @xref{The Development Environments}.
2871 This package specifies the options used by the linker.
2872 @xref{Main Subprograms}.
2874 This package specifies the options used when calling the tool
2875 @command{gnatmetric} via the @command{gnat} driver. Its attributes
2876 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2877 package @code{Builder}.
2879 This package specifies the naming conventions that apply
2880 to the source files in a project. In particular, these conventions are
2881 used to automatically find all source files in the source directories,
2882 or given a file name to find out its language for proper processing.
2883 @xref{Naming Schemes}.
2884 @item Pretty_Printer
2885 This package specifies the options used when calling the formatting tool
2886 @command{gnatpp} via the @command{gnat} driver. Its attributes
2887 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2888 package @code{Builder}.
2890 This package specifies the options used when calling the tool
2891 @command{gnatstack} via the @command{gnat} driver. Its attributes
2892 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2893 package @code{Builder}.
2895 This package specifies the options used when calling the tool
2896 @command{gnatsync} via the @command{gnat} driver.
2900 In its simplest form, a package may be empty:
2902 @smallexample @c projectfile
2912 A package may contain @b{attribute declarations},
2913 @b{variable declarations} and @b{case constructions}, as will be
2916 When there is ambiguity between a project name and a package name,
2917 the name always designates the project. To avoid possible confusion, it is
2918 always a good idea to avoid naming a project with one of the
2919 names allowed for packages or any name that starts with @code{gnat}.
2921 A package can also be defined by a @b{renaming declaration}. The new package
2922 renames a package declared in a different project file, and has the same
2923 attributes as the package it renames. The name of the renamed package
2924 must be the same as the name of the renaming package. The project must
2925 contain a package declaration with this name, and the project
2926 must appear in the context clause of the current project, or be its parent
2927 project. It is not possible to add or override attributes to the renaming
2928 project. If you need to do so, you should use an @b{extending declaration}
2931 Packages that are renamed in other project files often come from project files
2932 that have no sources: they are just used as templates. Any modification in the
2933 template will be reflected automatically in all the project files that rename
2934 a package from the template. This is a very common way to share settings
2937 Finally, a package can also be defined by an @b{extending declaration}. This is
2938 similar to a @b{renaming declaration}, except that it is possible to add or
2939 override attributes.
2942 package_declaration ::= package_spec | package_renaming | package_extension
2944 @i{package} @i{<package_>}simple_name @i{is}
2945 @{simple_declarative_item@}
2946 @i{end} package_identifier ;
2947 package_renaming ::==
2948 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
2949 package_extension ::==
2950 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
2951 @{simple_declarative_item@}
2952 @i{end} package_identifier ;
2955 @c ---------------------------------------------
2957 @subsection Expressions
2958 @c ---------------------------------------------
2961 An expression is any value that can be assigned to an attribute or a
2962 variable. It is either a literal value, or a construct requiring runtime
2963 computation by the project manager. In a project file, the computed value of
2964 an expression is either a string or a list of strings.
2966 A string value is one of:
2968 @item A literal string, for instance @code{"comm/my_proj.gpr"}
2969 @item The name of a variable that evaluates to a string (@pxref{Variables})
2970 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
2971 @item An external reference (@pxref{External Values})
2972 @item A concatenation of the above, as in @code{"prefix_" & Var}.
2977 A list of strings is one of the following:
2980 @item A parenthesized comma-separated list of zero or more string expressions, for
2981 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
2982 @item The name of a variable that evaluates to a list of strings
2983 @item The name of an attribute that evaluates to a list of strings
2984 @item A concatenation of a list of strings and a string (as defined above), for
2985 instance @code{("A", "B") & "C"}
2986 @item A concatenation of two lists of strings
2991 The following is the grammar for expressions
2994 string_literal ::= "@{string_element@}" -- Same as Ada
2995 string_expression ::= string_literal
2998 | attribute_reference
2999 | ( string_expression @{ & string_expression @} )
3000 string_list ::= ( string_expression @{ , string_expression @} )
3001 | @i{string_variable}_name
3002 | @i{string_}attribute_reference
3003 term ::= string_expression | string_list
3004 expression ::= term @{ & term @} -- Concatenation
3008 Concatenation involves strings and list of strings. As soon as a list of
3009 strings is involved, the result of the concatenation is a list of strings. The
3010 following Ada declarations show the existing operators:
3012 @smallexample @c ada
3013 function "&" (X : String; Y : String) return String;
3014 function "&" (X : String_List; Y : String) return String_List;
3015 function "&" (X : String_List; Y : String_List) return String_List;
3019 Here are some specific examples:
3021 @smallexample @c projectfile
3023 List := () & File_Name; -- One string in this list
3024 List2 := List & (File_Name & ".orig"); -- Two strings
3025 Big_List := List & Lists2; -- Three strings
3026 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
3030 @c ---------------------------------------------
3031 @node External Values
3032 @subsection External Values
3033 @c ---------------------------------------------
3036 An external value is an expression whose value is obtained from the command
3037 that invoked the processing of the current project file (typically a
3038 gnatmake or gprbuild command).
3040 There are two kinds of external values, one that returns a single string, and
3041 one that returns a string list.
3043 The syntax of a single string external value is:
3046 external_value ::= @i{external} ( string_literal [, string_literal] )
3050 The first string_literal is the string to be used on the command line or
3051 in the environment to specify the external value. The second string_literal,
3052 if present, is the default to use if there is no specification for this
3053 external value either on the command line or in the environment.
3055 Typically, the external value will either exist in the
3056 ^environment variables^logical name^
3057 or be specified on the command line through the
3058 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
3059 are specified, then the command line value is used, so that a user can more
3060 easily override the value.
3062 The function @code{external} always returns a string. It is an error if the
3063 value was not found in the environment and no default was specified in the
3064 call to @code{external}.
3066 An external reference may be part of a string expression or of a string
3067 list expression, and can therefore appear in a variable declaration or
3068 an attribute declaration.
3070 Most of the time, this construct is used to initialize typed variables, which
3071 are then used in @b{case} statements to control the value assigned to
3072 attributes in various scenarios. Thus such variables are often called
3073 @b{scenario variables}.
3075 The syntax for a string list external value is:
3078 external_value ::= @i{external_as_list} ( string_literal , string_literal )
3082 The first string_literal is the string to be used on the command line or
3083 in the environment to specify the external value. The second string_literal is
3084 the separator between each component of the string list.
3086 If the external value does not exist in the environment or on the command line,
3087 the result is an empty list. This is also the case, if the separator is an
3088 empty string or if the external value is only one separator.
3090 Any separator at the beginning or at the end of the external value is
3091 discarded. Then, if there is no separator in the external value, the result is
3092 a string list with only one string. Otherwise, any string between the beginning
3093 and the first separator, between two consecutive separators and between the
3094 last separator and the end are components of the string list.
3097 @i{external_as_list} ("SWITCHES", ",")
3101 If the external value is "-O2,-g", the result is ("-O2", "-g").
3103 If the external value is ",-O2,-g,", the result is also ("-O2", "-g").
3105 if the external value is "-gnav", the result is ("-gnatv").
3107 If the external value is ",,", the result is ("").
3109 If the external value is ",", the result is (), the empty string list.
3111 @c ---------------------------------------------
3112 @node Typed String Declaration
3113 @subsection Typed String Declaration
3114 @c ---------------------------------------------
3117 A @b{type declaration} introduces a discrete set of string literals.
3118 If a string variable is declared to have this type, its value
3119 is restricted to the given set of literals. These are the only named
3120 types in project files. A string type may only be declared at the project
3121 level, not inside a package.
3124 typed_string_declaration ::=
3125 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
3129 The string literals in the list are case sensitive and must all be different.
3130 They may include any graphic characters allowed in Ada, including spaces.
3131 Here is an example of a string type declaration:
3133 @smallexample @c projectfile
3134 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
3138 Variables of a string type are called @b{typed variables}; all other
3139 variables are called @b{untyped variables}. Typed variables are
3140 particularly useful in @code{case} constructions, to support conditional
3141 attribute declarations. (@pxref{Case Statements}).
3143 A string type may be referenced by its name if it has been declared in the same
3144 project file, or by an expanded name whose prefix is the name of the project
3145 in which it is declared.
3147 @c ---------------------------------------------
3149 @subsection Variables
3150 @c ---------------------------------------------
3153 @b{Variables} store values (strings or list of strings) and can appear
3154 as part of an expression. The declaration of a variable creates the
3155 variable and assigns the value of the expression to it. The name of the
3156 variable is available immediately after the assignment symbol, if you
3157 need to reuse its old value to compute the new value. Before the completion
3158 of its first declaration, the value of a variable defaults to the empty
3161 A @b{typed} variable can be used as part of a @b{case} expression to
3162 compute the value, but it can only be declared once in the project file,
3163 so that all case statements see the same value for the variable. This
3164 provides more consistency and makes the project easier to understand.
3165 The syntax for its declaration is identical to the Ada syntax for an
3166 object declaration. In effect, a typed variable acts as a constant.
3168 An @b{untyped} variable can be declared and overridden multiple times
3169 within the same project. It is declared implicitly through an Ada
3170 assignment. The first declaration establishes the kind of the variable
3171 (string or list of strings) and successive declarations must respect
3172 the initial kind. Assignments are executed in the order in which they
3173 appear, so the new value replaces the old one and any subsequent reference
3174 to the variable uses the new value.
3176 A variable may be declared at the project file level, or within a package.
3179 typed_variable_declaration ::=
3180 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
3181 variable_declaration ::= @i{<variable_>}simple_name := expression;
3185 Here are some examples of variable declarations:
3187 @smallexample @c projectfile
3189 This_OS : OS := external ("OS"); -- a typed variable declaration
3190 That_OS := "GNU/Linux"; -- an untyped variable declaration
3192 Name := "readme.txt";
3193 Save_Name := Name & ".saved";
3196 List_With_One_Element := ("-gnaty");
3197 List_With_Two_Elements := List_With_One_Element & "-gnatg";
3198 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
3203 A @b{variable reference} may take several forms:
3206 @item The simple variable name, for a variable in the current package (if any)
3207 or in the current project
3208 @item An expanded name, whose prefix is a context name.
3213 A @b{context} may be one of the following:
3216 @item The name of an existing package in the current project
3217 @item The name of an imported project of the current project
3218 @item The name of an ancestor project (i.e., a project extended by the current
3219 project, either directly or indirectly)
3220 @item An expanded name whose prefix is an imported/parent project name, and
3221 whose selector is a package name in that project.
3225 @c ---------------------------------------------
3227 @subsection Attributes
3228 @c ---------------------------------------------
3231 A project (and its packages) may have @b{attributes} that define
3232 the project's properties. Some attributes have values that are strings;
3233 others have values that are string lists.
3236 attribute_declaration ::=
3237 simple_attribute_declaration | indexed_attribute_declaration
3238 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
3239 indexed_attribute_declaration ::=
3240 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
3241 attribute_designator ::=
3242 @i{<simple_attribute_>}simple_name
3243 | @i{<indexed_attribute_>}simple_name ( string_literal )
3247 There are two categories of attributes: @b{simple attributes}
3248 and @b{indexed attributes}.
3249 Each simple attribute has a default value: the empty string (for string
3250 attributes) and the empty list (for string list attributes).
3251 An attribute declaration defines a new value for an attribute, and overrides
3252 the previous value. The syntax of a simple attribute declaration is similar to
3253 that of an attribute definition clause in Ada.
3255 Some attributes are indexed. These attributes are mappings whose
3256 domain is a set of strings. They are declared one association
3257 at a time, by specifying a point in the domain and the corresponding image
3259 Like untyped variables and simple attributes, indexed attributes
3260 may be declared several times. Each declaration supplies a new value for the
3261 attribute, and replaces the previous setting.
3263 Here are some examples of attribute declarations:
3265 @smallexample @c projectfile
3266 -- simple attributes
3267 for Object_Dir use "objects";
3268 for Source_Dirs use ("units", "test/drivers");
3270 -- indexed attributes
3271 for Body ("main") use "Main.ada";
3272 for Switches ("main.ada") use ("-v", "-gnatv");
3273 for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
3275 -- indexed attributes copy (from package Builder in project Default)
3276 -- The package name must always be specified, even if it is the current
3278 for Default_Switches use Default.Builder'Default_Switches;
3282 Attributes references may be appear anywhere in expressions, and are used
3283 to retrieve the value previously assigned to the attribute. If an attribute
3284 has not been set in a given package or project, its value defaults to the
3285 empty string or the empty list.
3288 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
3289 attribute_prefix ::= @i{project}
3290 | @i{<project_>}simple_name
3291 | package_identifier
3292 | @i{<project_>}simple_name . package_identifier
3298 @smallexample @c projectfile
3300 Naming'Dot_Replacement
3301 Imported_Project'Source_Dirs
3302 Imported_Project.Naming'Casing
3303 Builder'Default_Switches ("Ada")
3307 The prefix of an attribute may be:
3310 @item @code{project} for an attribute of the current project
3311 @item The name of an existing package of the current project
3312 @item The name of an imported project
3313 @item The name of a parent project that is extended by the current project
3314 @item An expanded name whose prefix is imported/parent project name,
3315 and whose selector is a package name
3320 Legal attribute names are listed below, including the package in
3321 which they must be declared. These names are case-insensitive. The
3322 semantics for the attributes is explained in great details in other sections.
3324 The column @emph{index} indicates whether the attribute is an indexed attribute,
3325 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
3326 system (file). The text is between brackets ([]) if the index is optional.
3328 @multitable @columnfractions .3 .1 .2 .4
3329 @headitem Attribute Name @tab Value @tab Package @tab Index
3330 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
3331 @item Name @tab string @tab - @tab (Read-only, name of project)
3332 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
3333 @item Source_Files @tab list @tab - @tab -
3334 @item Source_Dirs @tab list @tab - @tab -
3335 @item Source_List_File @tab string @tab - @tab -
3336 @item Locally_Removed_Files @tab list @tab - @tab -
3337 @item Excluded_Source_Files @tab list @tab - @tab -
3338 @item Object_Dir @tab string @tab - @tab -
3339 @item Exec_Dir @tab string @tab - @tab -
3340 @item Excluded_Source_Dirs @tab list @tab - @tab -
3341 @item Excluded_Source_Files @tab list @tab - @tab -
3342 @item Excluded_Source_List_File @tab list @tab - @tab -
3343 @item Inherit_Source_Path @tab list @tab - @tab insensitive
3344 @item Languages @tab list @tab - @tab -
3345 @item Main @tab list @tab - @tab -
3346 @item Main_Language @tab string @tab - @tab -
3347 @item Externally_Built @tab string @tab - @tab -
3348 @item Roots @tab list @tab - @tab file
3350 Library-related attributes @tab @tab @tab @pxref{Library Projects}
3351 @item Library_Dir @tab string @tab - @tab -
3352 @item Library_Name @tab string @tab - @tab -
3353 @item Library_Kind @tab string @tab - @tab -
3354 @item Library_Version @tab string @tab - @tab -
3355 @item Library_Interface @tab string @tab - @tab -
3356 @item Library_Auto_Init @tab string @tab - @tab -
3357 @item Library_Options @tab list @tab - @tab -
3358 @item Leading_Library_Options @tab list @tab - @tab -
3359 @item Library_Src_Dir @tab string @tab - @tab -
3360 @item Library_ALI_Dir @tab string @tab - @tab -
3361 @item Library_GCC @tab string @tab - @tab -
3362 @item Library_Symbol_File @tab string @tab - @tab -
3363 @item Library_Symbol_Policy @tab string @tab - @tab -
3364 @item Library_Reference_Symbol_File @tab string @tab - @tab -
3365 @item Interfaces @tab list @tab - @tab -
3367 Naming @tab @tab @tab @pxref{Naming Schemes}
3368 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
3369 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
3370 @item Separate_Suffix @tab string @tab Naming @tab -
3371 @item Casing @tab string @tab Naming @tab -
3372 @item Dot_Replacement @tab string @tab Naming @tab -
3373 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
3374 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
3375 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
3376 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
3378 Building @tab @tab @tab @pxref{Switches and Project Files}
3379 @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)
3380 @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)
3381 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
3382 @item Local_Config_File @tab string @tab insensitive @tab -
3383 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
3384 @item Global_Compilation_Switches @tab list @tab Builder @tab language
3385 @item Executable @tab string @tab Builder @tab [file]
3386 @item Executable_Suffix @tab string @tab Builder @tab -
3387 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
3389 IDE (used and created by GPS) @tab @tab @tab
3390 @item Remote_Host @tab string @tab IDE @tab -
3391 @item Program_Host @tab string @tab IDE @tab -
3392 @item Communication_Protocol @tab string @tab IDE @tab -
3393 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
3394 @item Debugger_Command @tab string @tab IDE @tab -
3395 @item Gnatlist @tab string @tab IDE @tab -
3396 @item Gnat @tab string @tab IDE @tab -
3397 @item VCS_Kind @tab string @tab IDE @tab -
3398 @item VCS_File_Check @tab string @tab IDE @tab -
3399 @item VCS_Log_Check @tab string @tab IDE @tab -
3400 @item Documentation_Dir @tab string @tab IDE @tab -
3402 Configuration files @tab @tab @tab See gprbuild manual
3403 @item Default_Language @tab string @tab - @tab -
3404 @item Run_Path_Option @tab list @tab - @tab -
3405 @item Run_Path_Origin @tab string @tab - @tab -
3406 @item Separate_Run_Path_Options @tab string @tab - @tab -
3407 @item Toolchain_Version @tab string @tab - @tab insensitive
3408 @item Toolchain_Description @tab string @tab - @tab insensitive
3409 @item Object_Generated @tab string @tab - @tab insensitive
3410 @item Objects_Linked @tab string @tab - @tab insensitive
3411 @item Target @tab string @tab - @tab -
3412 @item Library_Builder @tab string @tab - @tab -
3413 @item Library_Support @tab string @tab - @tab -
3414 @item Archive_Builder @tab list @tab - @tab -
3415 @item Archive_Builder_Append_Option @tab list @tab - @tab -
3416 @item Archive_Indexer @tab list @tab - @tab -
3417 @item Archive_Suffix @tab string @tab - @tab -
3418 @item Library_Partial_Linker @tab list @tab - @tab -
3419 @item Shared_Library_Prefix @tab string @tab - @tab -
3420 @item Shared_Library_Suffix @tab string @tab - @tab -
3421 @item Symbolic_Link_Supported @tab string @tab - @tab -
3422 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
3423 @item Library_Auto_Init_Supported @tab string @tab - @tab -
3424 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
3425 @item Library_Version_Switches @tab list @tab - @tab -
3426 @item Library_Install_Name_Option @tab string @tab - @tab -
3427 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
3428 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
3429 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
3430 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
3431 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3432 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3433 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
3434 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
3435 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
3436 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
3437 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
3438 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitive (language)
3439 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
3440 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
3441 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
3442 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
3443 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
3444 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3445 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3446 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
3447 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3448 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3449 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
3450 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
3451 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
3452 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
3453 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
3454 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
3455 @item Prefix @tab string @tab Binder @tab insensitive (language)
3456 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
3457 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
3458 @item Linker_Options @tab list @tab Linker @tab -
3459 @item Leading_Switches @tab list @tab Linker @tab -
3460 @item Map_File_Options @tab string @tab Linker @tab -
3461 @item Executable_Switches @tab list @tab Linker @tab -
3462 @item Lib_Dir_Switch @tab string @tab Linker @tab -
3463 @item Lib_Name_Switch @tab string @tab Linker @tab -
3464 @item Max_Command_Line_Length @tab string @tab Linker @tab -
3465 @item Response_File_Format @tab string @tab Linker @tab -
3466 @item Response_File_Switches @tab list @tab Linker @tab -
3469 @c ---------------------------------------------
3470 @node Case Statements
3471 @subsection Case Statements
3472 @c ---------------------------------------------
3475 A @b{case} statement is used in a project file to effect conditional
3476 behavior. Through this statement, you can set the value of attributes
3477 and variables depending on the value previously assigned to a typed
3480 All choices in a choice list must be distinct. Unlike Ada, the choice
3481 lists of all alternatives do not need to include all values of the type.
3482 An @code{others} choice must appear last in the list of alternatives.
3484 The syntax of a @code{case} construction is based on the Ada case statement
3485 (although the @code{null} statement for empty alternatives is optional).
3487 The case expression must be a typed string variable, whose value is often
3488 given by an external reference (@pxref{External Values}).
3490 Each alternative starts with the reserved word @code{when}, either a list of
3491 literal strings separated by the @code{"|"} character or the reserved word
3492 @code{others}, and the @code{"=>"} token.
3493 Each literal string must belong to the string type that is the type of the
3495 After each @code{=>}, there are zero or more statements. The only
3496 statements allowed in a case construction are other case statements,
3497 attribute declarations and variable declarations. String type declarations and
3498 package declarations are not allowed. Variable declarations are restricted to
3499 variables that have already been declared before the case construction.
3503 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
3506 @i{when} discrete_choice_list =>
3508 | attribute_declaration
3509 | variable_declaration
3510 | empty_declaration@}
3512 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
3516 Here is a typical example:
3518 @smallexample @c projectfile
3521 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
3522 OS : OS_Type := external ("OS", "GNU/Linux");
3526 when "GNU/Linux" | "Unix" =>
3527 for Switches ("Ada") use ("-gnath");
3529 for Switches ("Ada") use ("-gnatP");
3538 @c ---------------------------------------------
3539 @node Tools Supporting Project Files
3540 @chapter Tools Supporting Project Files
3541 @c ---------------------------------------------
3547 * gnatmake and Project Files::
3548 * The GNAT Driver and Project Files::
3549 * The Development Environments::
3550 * Cleaning up with GPRclean::
3553 @c ---------------------------------------------
3554 @node gnatmake and Project Files
3555 @section gnatmake and Project Files
3556 @c ---------------------------------------------
3559 This section covers several topics related to @command{gnatmake} and
3560 project files: defining ^switches^switches^ for @command{gnatmake}
3561 and for the tools that it invokes; specifying configuration pragmas;
3562 the use of the @code{Main} attribute; building and rebuilding library project
3566 * Switches Related to Project Files::
3567 * Switches and Project Files::
3568 * Specifying Configuration Pragmas::
3569 * Project Files and Main Subprograms::
3570 * Library Project Files::
3573 @c ---------------------------------------------
3574 @node Switches Related to Project Files
3575 @subsection Switches Related to Project Files
3576 @c ---------------------------------------------
3579 The following switches are used by GNAT tools that support project files:
3583 @item ^-P^/PROJECT_FILE=^@var{project}
3584 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
3585 Indicates the name of a project file. This project file will be parsed with
3586 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
3587 if any, and using the external references indicated
3588 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
3590 There may zero, one or more spaces between @option{-P} and @var{project}.
3593 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3595 Since the Project Manager parses the project file only after all the switches
3596 on the command line are checked, the order of the switches
3597 @option{^-P^/PROJECT_FILE^},
3598 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3599 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3601 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3602 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3603 Indicates that external variable @var{name} has the value @var{value}.
3604 The Project Manager will use this value for occurrences of
3605 @code{external(name)} when parsing the project file.
3608 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3616 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3617 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3618 @var{name}, only the last one is used.
3620 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3621 takes precedence over the value of the same name in the environment.
3623 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3624 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3625 Indicates the verbosity of the parsing of GNAT project files.
3628 @option{-vP0} means Default;
3629 @option{-vP1} means Medium;
3630 @option{-vP2} means High.
3634 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3638 The default is ^Default^DEFAULT^: no output for syntactically correct
3640 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3641 only the last one is used.
3643 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3644 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3645 Add directory <dir> at the beginning of the project search path, in order,
3646 after the current working directory.
3650 @cindex @option{-eL} (any project-aware tool)
3651 Follow all symbolic links when processing project files.
3654 @item ^--subdirs^/SUBDIRS^=<subdir>
3655 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3656 This switch is recognized by gnatmake and gnatclean. It indicate that the real
3657 directories (except the source directories) are the subdirectories <subdir>
3658 of the directories specified in the project files. This applies in particular
3659 to object directories, library directories and exec directories. If the
3660 subdirectories do not exist, they are created automatically.
3664 @c ---------------------------------------------
3665 @node Switches and Project Files
3666 @subsection Switches and Project Files
3667 @c ---------------------------------------------
3671 It is not currently possible to specify VMS style qualifiers in the project
3672 files; only Unix style ^switches^switches^ may be specified.
3675 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3676 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3677 attribute, a @code{Switches} attribute, or both;
3678 as their names imply, these ^switch^switch^-related
3679 attributes affect the ^switches^switches^ that are used for each of these GNAT
3681 @command{gnatmake} is invoked. As will be explained below, these
3682 component-specific ^switches^switches^ precede
3683 the ^switches^switches^ provided on the @command{gnatmake} command line.
3685 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3686 indexed by language name (case insensitive) whose value is a string list.
3689 @smallexample @c projectfile
3692 for ^Default_Switches^Default_Switches^ ("Ada")
3693 use ("^-gnaty^-gnaty^",
3700 The @code{Switches} attribute is indexed on a file name (which may or may
3701 not be case sensitive, depending
3702 on the operating system) whose value is a string list. For example:
3704 @smallexample @c projectfile
3707 for Switches ("main1.adb")
3709 for Switches ("main2.adb")
3716 For the @code{Builder} package, the file names must designate source files
3717 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
3718 file names must designate @file{ALI} or source files for main subprograms.
3719 In each case just the file name without an explicit extension is acceptable.
3721 For each tool used in a program build (@command{gnatmake}, the compiler, the
3722 binder, and the linker), the corresponding package @dfn{contributes} a set of
3723 ^switches^switches^ for each file on which the tool is invoked, based on the
3724 ^switch^switch^-related attributes defined in the package.
3725 In particular, the ^switches^switches^
3726 that each of these packages contributes for a given file @var{f} comprise:
3729 @item the value of attribute @code{Switches (@var{f})},
3730 if it is specified in the package for the given file,
3731 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
3732 if it is specified in the package.
3737 If neither of these attributes is defined in the package, then the package does
3738 not contribute any ^switches^switches^ for the given file.
3740 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
3741 two sets, in the following order: those contributed for the file
3742 by the @code{Builder} package;
3743 and the switches passed on the command line.
3745 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
3746 the ^switches^switches^ passed to the tool comprise three sets,
3747 in the following order:
3751 the applicable ^switches^switches^ contributed for the file
3752 by the @code{Builder} package in the project file supplied on the command line;
3755 those contributed for the file by the package (in the relevant project file --
3756 see below) corresponding to the tool; and
3759 the applicable switches passed on the command line.
3762 The term @emph{applicable ^switches^switches^} reflects the fact that
3763 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
3764 tools, depending on the individual ^switch^switch^.
3766 @command{gnatmake} may invoke the compiler on source files from different
3767 projects. The Project Manager will use the appropriate project file to
3768 determine the @code{Compiler} package for each source file being compiled.
3769 Likewise for the @code{Binder} and @code{Linker} packages.
3771 As an example, consider the following package in a project file:
3773 @smallexample @c projectfile
3777 for ^Default_Switches^Default_Switches^ ("Ada")
3779 for Switches ("a.adb")
3781 for Switches ("b.adb")
3790 If @command{gnatmake} is invoked with this project file, and it needs to
3791 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
3792 @file{a.adb} will be compiled with the ^switch^switch^
3794 @file{b.adb} with ^switches^switches^
3796 and @option{^-gnaty^-gnaty^},
3797 and @file{c.adb} with @option{^-g^-g^}.
3799 The following example illustrates the ordering of the ^switches^switches^
3800 contributed by different packages:
3802 @smallexample @c projectfile
3806 for Switches ("main.adb")
3815 for Switches ("main.adb")
3823 If you issue the command:
3826 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
3830 then the compiler will be invoked on @file{main.adb} with the following
3831 sequence of ^switches^switches^
3834 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
3838 with the last @option{^-O^-O^}
3839 ^switch^switch^ having precedence over the earlier ones;
3840 several other ^switches^switches^
3841 (such as @option{^-c^-c^}) are added implicitly.
3843 The ^switches^switches^
3845 and @option{^-O1^-O1^} are contributed by package
3846 @code{Builder}, @option{^-O2^-O2^} is contributed
3847 by the package @code{Compiler}
3848 and @option{^-O0^-O0^} comes from the command line.
3850 The @option{^-g^-g^}
3851 ^switch^switch^ will also be passed in the invocation of
3854 A final example illustrates switch contributions from packages in different
3857 @smallexample @c projectfile
3860 for Source_Files use ("pack.ads", "pack.adb");
3862 for ^Default_Switches^Default_Switches^ ("Ada")
3863 use ("^-gnata^-gnata^");
3871 for Source_Files use ("foo_main.adb", "bar_main.adb");
3873 for Switches ("foo_main.adb")
3883 procedure Foo_Main is
3892 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
3896 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
3897 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
3898 @option{^-gnato^-gnato^} (passed on the command line).
3899 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
3900 are @option{^-g^-g^} from @code{Proj4.Builder},
3901 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
3902 and @option{^-gnato^-gnato^} from the command line.
3904 When using @command{gnatmake} with project files, some ^switches^switches^ or
3905 arguments may be expressed as relative paths. As the working directory where
3906 compilation occurs may change, these relative paths are converted to absolute
3907 paths. For the ^switches^switches^ found in a project file, the relative paths
3908 are relative to the project file directory, for the switches on the command
3909 line, they are relative to the directory where @command{gnatmake} is invoked.
3910 The ^switches^switches^ for which this occurs are:
3916 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
3918 ^-o^-o^, object files specified in package @code{Linker} or after
3919 -largs on the command line). The exception to this rule is the ^switch^switch^
3920 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
3922 @c ---------------------------------------------
3923 @node Specifying Configuration Pragmas
3924 @subsection Specifying Configuration Pragmas
3925 @c ---------------------------------------------
3928 When using @command{gnatmake} with project files, if there exists a file
3929 @file{gnat.adc} that contains configuration pragmas, this file will be
3932 Configuration pragmas can be defined by means of the following attributes in
3933 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
3934 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
3936 Both these attributes are single string attributes. Their values is the path
3937 name of a file containing configuration pragmas. If a path name is relative,
3938 then it is relative to the project directory of the project file where the
3939 attribute is defined.
3941 When compiling a source, the configuration pragmas used are, in order,
3942 those listed in the file designated by attribute
3943 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
3944 project file, if it is specified, and those listed in the file designated by
3945 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
3946 the project file of the source, if it exists.
3948 @c ---------------------------------------------
3949 @node Project Files and Main Subprograms
3950 @subsection Project Files and Main Subprograms
3951 @c ---------------------------------------------
3954 When using a project file, you can invoke @command{gnatmake}
3955 with one or several main subprograms, by specifying their source files on the
3959 gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
3963 Each of these needs to be a source file of the same project, except
3964 when the switch ^-u^/UNIQUE^ is used.
3966 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
3967 same project, one of the project in the tree rooted at the project specified
3968 on the command line. The package @code{Builder} of this common project, the
3969 "main project" is the one that is considered by @command{gnatmake}.
3971 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
3972 imported directly or indirectly by the project specified on the command line.
3973 Note that if such a source file is not part of the project specified on the
3974 command line, the ^switches^switches^ found in package @code{Builder} of the
3975 project specified on the command line, if any, that are transmitted
3976 to the compiler will still be used, not those found in the project file of
3979 When using a project file, you can also invoke @command{gnatmake} without
3980 explicitly specifying any main, and the effect depends on whether you have
3981 defined the @code{Main} attribute. This attribute has a string list value,
3982 where each element in the list is the name of a source file (the file
3983 extension is optional) that contains a unit that can be a main subprogram.
3985 If the @code{Main} attribute is defined in a project file as a non-empty
3986 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
3987 line, then invoking @command{gnatmake} with this project file but without any
3988 main on the command line is equivalent to invoking @command{gnatmake} with all
3989 the file names in the @code{Main} attribute on the command line.
3992 @smallexample @c projectfile
3995 for Main use ("main1", "main2", "main3");
4001 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
4003 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
4005 When the project attribute @code{Main} is not specified, or is specified
4006 as an empty string list, or when the switch @option{-u} is used on the command
4007 line, then invoking @command{gnatmake} with no main on the command line will
4008 result in all immediate sources of the project file being checked, and
4009 potentially recompiled. Depending on the presence of the switch @option{-u},
4010 sources from other project files on which the immediate sources of the main
4011 project file depend are also checked and potentially recompiled. In other
4012 words, the @option{-u} switch is applied to all of the immediate sources of the
4015 When no main is specified on the command line and attribute @code{Main} exists
4016 and includes several mains, or when several mains are specified on the
4017 command line, the default ^switches^switches^ in package @code{Builder} will
4018 be used for all mains, even if there are specific ^switches^switches^
4019 specified for one or several mains.
4021 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
4022 the specific ^switches^switches^ for each main, if they are specified.
4024 @c ---------------------------------------------
4025 @node Library Project Files
4026 @subsection Library Project Files
4027 @c ---------------------------------------------
4030 When @command{gnatmake} is invoked with a main project file that is a library
4031 project file, it is not allowed to specify one or more mains on the command
4034 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
4035 ^-l^/ACTION=LINK^ have special meanings.
4038 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
4039 to @command{gnatmake} that @command{gnatbind} should be invoked for the
4042 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
4043 to @command{gnatmake} that the binder generated file should be compiled
4044 (in the case of a stand-alone library) and that the library should be built.
4048 @c ---------------------------------------------
4049 @node The GNAT Driver and Project Files
4050 @section The GNAT Driver and Project Files
4051 @c ---------------------------------------------
4054 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
4055 can benefit from project files:
4056 (@command{^gnatbind^gnatbind^},
4057 @command{^gnatcheck^gnatcheck^},
4058 @command{^gnatclean^gnatclean^},
4059 @command{^gnatelim^gnatelim^},
4060 @command{^gnatfind^gnatfind^},
4061 @command{^gnatlink^gnatlink^},
4062 @command{^gnatls^gnatls^},
4063 @command{^gnatmetric^gnatmetric^},
4064 @command{^gnatpp^gnatpp^},
4065 @command{^gnatstub^gnatstub^},
4066 and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
4067 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
4068 They must be invoked through the @command{gnat} driver.
4070 The @command{gnat} driver is a wrapper that accepts a number of commands and
4071 calls the corresponding tool. It was designed initially for VMS platforms (to
4072 convert VMS qualifiers to Unix-style switches), but it is now available on all
4075 On non-VMS platforms, the @command{gnat} driver accepts the following commands
4079 @item BIND to invoke @command{^gnatbind^gnatbind^}
4080 @item CHOP to invoke @command{^gnatchop^gnatchop^}
4081 @item CLEAN to invoke @command{^gnatclean^gnatclean^}
4082 @item COMP or COMPILE to invoke the compiler
4083 @item ELIM to invoke @command{^gnatelim^gnatelim^}
4084 @item FIND to invoke @command{^gnatfind^gnatfind^}
4085 @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
4086 @item LINK to invoke @command{^gnatlink^gnatlink^}
4087 @item LS or LIST to invoke @command{^gnatls^gnatls^}
4088 @item MAKE to invoke @command{^gnatmake^gnatmake^}
4089 @item NAME to invoke @command{^gnatname^gnatname^}
4090 @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
4091 @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
4092 @item METRIC to invoke @command{^gnatmetric^gnatmetric^}
4093 @item STUB to invoke @command{^gnatstub^gnatstub^}
4094 @item XREF to invoke @command{^gnatxref^gnatxref^}
4099 (note that the compiler is invoked using the command
4100 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
4102 On non-VMS platforms, between @command{gnat} and the command, two
4103 special switches may be used:
4106 @item @command{-v} to display the invocation of the tool.
4107 @item @command{-dn} to prevent the @command{gnat} driver from removing
4108 the temporary files it has created. These temporary files are
4109 configuration files and temporary file list files.
4114 The command may be followed by switches and arguments for the invoked
4118 gnat bind -C main.ali
4124 Switches may also be put in text files, one switch per line, and the text
4125 files may be specified with their path name preceded by '@@'.
4128 gnat bind @@args.txt main.ali
4132 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
4133 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
4134 (@option{^-P^/PROJECT_FILE^},
4135 @option{^-X^/EXTERNAL_REFERENCE^} and
4136 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
4137 the switches of the invoking tool.
4139 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
4140 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
4141 the immediate sources of the specified project file.
4143 When GNAT METRIC is used with a project file, but with no source
4144 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
4145 with all the immediate sources of the specified project file and with
4146 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
4149 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
4150 a project file, no source is specified on the command line and
4151 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
4152 the underlying tool (^gnatpp^gnatpp^ or
4153 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
4154 not only for the immediate sources of the main project.
4156 (-U stands for Universal or Union of the project files of the project tree)
4159 For each of the following commands, there is optionally a corresponding
4160 package in the main project.
4163 @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
4165 @item package @code{Check} for command CHECK (invoking
4166 @code{^gnatcheck^gnatcheck^})
4168 @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
4170 @item package @code{Cross_Reference} for command XREF (invoking
4171 @code{^gnatxref^gnatxref^})
4173 @item package @code{Eliminate} for command ELIM (invoking
4174 @code{^gnatelim^gnatelim^})
4176 @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
4178 @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
4180 @item package @code{Gnatstub} for command STUB
4181 (invoking @code{^gnatstub^gnatstub^})
4183 @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
4185 @item package @code{Check} for command CHECK
4186 (invoking @code{^gnatcheck^gnatcheck^})
4188 @item package @code{Metrics} for command METRIC
4189 (invoking @code{^gnatmetric^gnatmetric^})
4191 @item package @code{Pretty_Printer} for command PP or PRETTY
4192 (invoking @code{^gnatpp^gnatpp^})
4197 Package @code{Gnatls} has a unique attribute @code{Switches},
4198 a simple variable with a string list value. It contains ^switches^switches^
4199 for the invocation of @code{^gnatls^gnatls^}.
4201 @smallexample @c projectfile
4214 All other packages have two attribute @code{Switches} and
4215 @code{^Default_Switches^Default_Switches^}.
4217 @code{Switches} is an indexed attribute, indexed by the
4218 source file name, that has a string list value: the ^switches^switches^ to be
4219 used when the tool corresponding to the package is invoked for the specific
4222 @code{^Default_Switches^Default_Switches^} is an attribute,
4223 indexed by the programming language that has a string list value.
4224 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
4225 ^switches^switches^ for the invocation of the tool corresponding
4226 to the package, except if a specific @code{Switches} attribute
4227 is specified for the source file.
4229 @smallexample @c projectfile
4233 for Source_Dirs use ("**");
4244 for ^Default_Switches^Default_Switches^ ("Ada")
4245 use ("^-gnatv^-gnatv^",
4246 "^-gnatwa^-gnatwa^");
4252 for ^Default_Switches^Default_Switches^ ("Ada")
4260 for ^Default_Switches^Default_Switches^ ("Ada")
4262 for Switches ("main.adb")
4271 for ^Default_Switches^Default_Switches^ ("Ada")
4278 package Cross_Reference is
4279 for ^Default_Switches^Default_Switches^ ("Ada")
4284 end Cross_Reference;
4290 With the above project file, commands such as
4293 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
4294 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
4295 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
4296 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
4297 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
4301 will set up the environment properly and invoke the tool with the switches
4302 found in the package corresponding to the tool:
4303 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
4304 except @code{Switches ("main.adb")}
4305 for @code{^gnatlink^gnatlink^}.
4306 It is also possible to invoke some of the tools,
4307 (@code{^gnatcheck^gnatcheck^},
4308 @code{^gnatmetric^gnatmetric^},
4309 and @code{^gnatpp^gnatpp^})
4310 on a set of project units thanks to the combination of the switches
4311 @option{-P}, @option{-U} and possibly the main unit when one is interested
4312 in its closure. For instance,
4318 will compute the metrics for all the immediate units of project
4321 gnat metric -Pproj -U
4325 will compute the metrics for all the units of the closure of projects
4326 rooted at @code{proj}.
4328 gnat metric -Pproj -U main_unit
4332 will compute the metrics for the closure of units rooted at
4333 @code{main_unit}. This last possibility relies implicitly
4334 on @command{gnatbind}'s option @option{-R}. But if the argument files for the
4335 tool invoked by the @command{gnat} driver are explicitly specified
4336 either directly or through the tool @option{-files} option, then the tool
4337 is called only for these explicitly specified files.
4339 @c ---------------------------------------------
4340 @node The Development Environments
4341 @section The Development Environments
4342 @c ---------------------------------------------
4345 See the appropriate manuals for more details. These environments will
4346 store a number of settings in the project itself, when they are meant
4347 to be shared by the whole team working on the project. Here are the
4348 attributes defined in the package @b{IDE} in projects.
4352 This is a simple attribute. Its value is a string that designates the remote
4353 host in a cross-compilation environment, to be used for remote compilation and
4354 debugging. This field should not be specified when running on the local
4358 This is a simple attribute. Its value is a string that specifies the
4359 name of IP address of the embedded target in a cross-compilation environment,
4360 on which the program should execute.
4362 @item Communication_Protocol
4363 This is a simple string attribute. Its value is the name of the protocol
4364 to use to communicate with the target in a cross-compilation environment,
4365 e.g.@: @code{"wtx"} or @code{"vxworks"}.
4367 @item Compiler_Command
4368 This is an associative array attribute, whose domain is a language name. Its
4369 value is string that denotes the command to be used to invoke the compiler.
4370 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
4371 gnatmake, in particular in the handling of switches.
4373 @item Debugger_Command
4374 This is simple attribute, Its value is a string that specifies the name of
4375 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
4377 @item Default_Switches
4378 This is an associative array attribute. Its indexes are the name of the
4379 external tools that the GNAT Programming System (GPS) is supporting. Its
4380 value is a list of switches to use when invoking that tool.
4383 This is a simple attribute. Its value is a string that specifies the name
4384 of the @command{gnatls} utility to be used to retrieve information about the
4385 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
4388 This is a simple attribute. Its value is a string used to specify the
4389 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
4390 ClearCase or Perforce.
4393 This is a simple attribute. Its value is a string that specifies the name
4394 of the @command{gnat} utility to be used when executing various tools from
4395 GPS, in particular @code{"gnat pp"}, @code{"gnat stub"},@dots{}
4397 @item VCS_File_Check
4398 This is a simple attribute. Its value is a string that specifies the
4399 command used by the VCS to check the validity of a file, either
4400 when the user explicitly asks for a check, or as a sanity check before
4404 This is a simple attribute. Its value is a string that specifies
4405 the command used by the VCS to check the validity of a log file.
4407 @item VCS_Repository_Root
4408 The VCS repository root path. This is used to create tags or branches
4409 of the repository. For subversion the value should be the @code{URL}
4410 as specified to check-out the working copy of the repository.
4412 @item VCS_Patch_Root
4413 The local root directory to use for building patch file. All patch chunks
4414 will be relative to this path. The root project directory is used if
4415 this value is not defined.
4419 @c ---------------------------------------------
4420 @node Cleaning up with GPRclean
4421 @section Cleaning up with GPRclean
4422 @c ---------------------------------------------
4425 The GPRclean tool removes the files created by GPRbuild.
4426 At a minimum, to invoke GPRclean you must specify a main project file
4427 in a command such as @code{gprclean proj.gpr} or @code{gprclean -P proj.gpr}.
4429 Examples of invocation of GPRclean:
4432 gprclean -r prj1.gpr
4433 gprclean -c -P prj2.gpr
4437 * Switches for GPRclean::
4440 @c ---------------------------------------------
4441 @node Switches for GPRclean
4442 @subsection Switches for GPRclean
4443 @c ---------------------------------------------
4446 The switches for GPRclean are:
4449 @item @option{--config=<main config project file name>} : Specify the
4450 configuration project file name
4452 @item @option{--autoconf=<config project file name>}
4454 This specifies a configuration project file name that already exists or will
4455 be created automatically. Option @option{--autoconf=}
4456 cannot be specified more than once. If the configuration project file
4457 specified with @option{--autoconf=} exists, then it is used. Otherwise,
4458 @value{gprconfig} is invoked to create it automatically.
4460 @item @option{-c} : Only delete compiler-generated files. Do not delete
4461 executables and libraries.
4463 @item @option{-f} : Force deletions of unwritable files
4465 @item @option{-F} : Display full project path name in brief error messages
4467 @item @option{-h} : Display this message
4469 @item @option{-n} : Do not delete files, only list files to delete
4471 @item @option{-P<proj>} : Use Project File @emph{<proj>}.
4473 @item @option{-q} : Be quiet/terse. There is no output, except to report
4476 @item @option{-r} : (recursive) Clean all projects referenced by the main
4477 project directly or indirectly. Without this switch, GPRclean only
4478 cleans the main project.
4480 @item @option{-v} : Verbose mode
4482 @item @option{-vPx} : Specify verbosity when parsing Project Files.
4483 x = 0 (default), 1 or 2.
4485 @item @option{-Xnm=val} : Specify an external reference for Project Files.