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 * Project File Reference::
24 @c ---------------------------------------------
27 @c ---------------------------------------------
30 This chapter describes GNAT's @emph{Project Manager}, a facility that allows
31 you to manage complex builds involving a number of source files, directories,
32 and options for different system configurations. In particular,
33 project files allow you to specify:
36 @item The directory or set of directories containing the source files, and/or the
37 names of the specific source files themselves
38 @item The directory in which the compiler's output
39 (@file{ALI} files, object files, tree files, etc.) is to be placed
40 @item The directory in which the executable programs are to be placed
41 @item Switch settings for any of the project-enabled tools;
42 you can apply these settings either globally or to individual compilation units.
43 @item The source files containing the main subprogram(s) to be built
44 @item The source programming language(s)
45 @item Source file naming conventions; you can specify these either globally or for
46 individual compilation units (@pxref{Naming Schemes}).
47 @item Change any of the above settings depending on external values, thus enabling
48 the reuse of the projects in various @b{scenarios} (@pxref{Scenarios
50 @item Automatically build libraries as part of the build process
51 (@pxref{Library Projects}).
56 Project files are written in a syntax close to that of Ada, using familiar
57 notions such as packages, context clauses, declarations, default values,
58 assignments, and inheritance (@pxref{Project File Reference}).
60 Project files can be built hierarchically from other project files, simplifying
61 complex system integration and project reuse (@pxref{Organizing Projects into
65 @item One project can import other projects containing needed source files.
66 More generally, the Project Manager lets you structure large development
67 efforts into hierarchical subsystems, where build decisions are delegated
68 to the subsystem level, and thus different compilation environments
69 (switch settings) used for different subsystems.
70 @item You can organize GNAT projects in a hierarchy: a child project
71 can extend a parent project, inheriting the parent's source files and
72 optionally overriding any of them with alternative versions
73 (@pxref{Project Extension}).
78 Several tools support project files, generally in addition to specifying
79 the information on the command line itself). They share common switches
80 to control the loading of the project (in particular
81 @option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
82 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).
83 @xref{Switches Related to Project Files}.
85 The Project Manager supports a wide range of development strategies,
86 for systems of all sizes. Here are some typical practices that are
90 @item Using a common set of source files and generating object files in different
91 directories via different switch settings. It can be used for instance, for
92 generating separate sets of object files for debugging and for production.
93 @item Using a mostly-shared set of source files with different versions of
94 some units or subunits. It can be used for instance, for grouping and hiding
98 all OS dependencies in a small number of implementation units.
100 Project files can be used to achieve some of the effects of a source
101 versioning system (for example, defining separate projects for
102 the different sets of sources that comprise different releases) but the
103 Project Manager is independent of any source configuration management tool
104 that might be used by the developers.
106 The various sections below introduce the different concepts related to
107 projects. Each section starts with examples and use cases, and then goes into
108 the details of related project file capabilities.
110 @c ---------------------------------------------
111 @node Building With Projects
112 @section Building With Projects
113 @c ---------------------------------------------
116 In its simplest form, a unique project is used to build a single executable.
117 This section concentrates on such a simple setup. Later sections will extend
118 this basic model to more complex setups.
120 The following concepts are the foundation of project files, and will be further
121 detailed later in this documentation. They are summarized here as a reference.
124 @item @b{Project file}:
125 A text file using an Ada-like syntax, generally using the @file{.gpr}
126 extension. It defines build-related characteristics of an application.
127 The characteristics include the list of sources, the location of those
128 sources, the location for the generated object files, the name of
129 the main program, and the options for the various tools involved in the
132 @item @b{Project attribute}:
133 A specific project characteristic is defined by an attribute clause. Its
134 value is a string or a sequence of strings. All settings in a project
135 are defined through a list of predefined attributes with precise
136 semantics. @xref{Attributes}.
138 @item @b{Package in a project}:
139 Global attributes are defined at the top level of a project.
140 Attributes affecting specific tools are grouped in a
141 package whose name is related to tool's function. The most common
142 packages are @code{Builder}, @code{Compiler}, @code{Binder},
143 and @code{Linker}. @xref{Packages}.
145 @item @b{Project variables}:
146 In addition to attributes, a project can use variables to store intermediate
147 values and avoid duplication in complex expressions. It can be initialized
148 with a value coming from the environment.
149 A frequent use of variables is to define scenarios.
150 @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.
152 @item @b{Source files} and @b{source directories}:
153 A source file is associated with a language through a naming convention. For
154 instance, @code{foo.c} is typically the name of a C source file;
155 @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a
156 file containing an Ada spec. A compilation unit is often composed of a main
157 source file and potentially several auxiliary ones, such as header files in C.
158 The naming conventions can be user defined @xref{Naming Schemes}, and will
159 drive the builder to call the appropriate compiler for the given source file.
160 Source files are searched for in the source directories associated with the
161 project through the @b{Source_Dirs} attribute. By default, all the files (in
162 these source directories) following the naming conventions associated with the
163 declared languages are considered to be part of the project. It is also
164 possible to limit the list of source files using the @b{Source_Files} or
165 @b{Source_List_File} attributes. Note that those last two attributes only
166 accept basenames with no directory information.
168 @item @b{Object files} and @b{object directory}:
169 An object file is an intermediate file produced by the compiler from a
170 compilation unit. It is used by post-compilation tools to produce
171 final executables or libraries. Object files produced in the context of
172 a given project are stored in a single directory that can be specified by the
173 @b{Object_Dir} attribute. In order to store objects in
174 two or more object directories, the system must be split into
175 distinct subsystems with their own project file.
179 The following subsections introduce gradually all the attributes of interest
180 for simple build needs. Here is the simple setup that will be used in the
183 The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in
184 the @file{common/} directory. The file @file{proc.adb} contains an Ada main
185 subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile
186 these source files with the switch @option{-O2}, and put the resulting files in
187 the directory @file{obj/}.
197 ^common/release/^[COMMON.RELEASE]^
198 proc.ali, proc.o pack.ali, pack.o
203 Our project is to be called @emph{Build}. The name of the
204 file is the name of the project (case-insensitive) with the
205 @file{.gpr} extension, therefore the project file name is @file{build.gpr}. This
206 is not mandatory, but a warning is issued when this convention is not followed.
208 This is a very simple example, and as stated above, a single project
209 file is enough for it. We will thus create a new file, that for now
210 should contain the following code:
213 @b{project} Build @b{is}
218 * Source Files and Directories::
219 * Object and Exec Directory::
221 * Tools Options in Project Files::
222 * Compiling with Project Files::
223 * Executable File Names::
224 * Avoid Duplication With Variables::
228 @c ---------------------------------------------
229 @node Source Files and Directories
230 @subsection Source Files and Directories
231 @c ---------------------------------------------
234 When you create a new project, the first thing to describe is how to find the
235 corresponding source files. This is the only settings that are needed by all
236 the tools that will use this project (builder, compiler, binder and linker for
237 the compilation, IDEs to edit the source files,@dots{}).
239 @cindex Source directories
240 First step is to declare the source directories, which are the directories
241 to be searched to find source files. In the case of the example,
242 the @file{common} directory is the only source directory.
244 @cindex @code{Source_Dirs}
245 There are several ways of defining source directories:
248 @item When the attribute @b{Source_Dirs} is not used, a project contains a
249 single source directory which is the one where the project file itself
250 resides. In our example, if @file{build.gpr} is placed in the @file{common}
251 directory, the project has the needed implicit source directory.
253 @item The attribute @b{Source_Dirs} can be set to a list of path names, one
254 for each of the source directories. Such paths can either be absolute
255 names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the
256 directory in which the project file resides (for instance "." if
257 @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
258 Each of the source directories must exist and be readable.
261 The syntax for directories is platform specific. For portability, however,
262 the project manager will always properly translate UNIX-like path names to
263 the native format of specific platform. For instance, when the same project
264 file is to be used both on Unix and Windows, "/" should be used as the
265 directory separator rather than "\".
267 @item The attribute @b{Source_Dirs} can automatically include subdirectories
268 using a special syntax inspired by some UNIX shells. If any of the path in
269 the list ends with @emph{"/**"}, then that path and all its subdirectories
270 (recursively) are included in the list of source directories. For instance,
271 @file{./**} represent the complete directory tree rooted at ".".
272 @cindex Source directories, recursive
274 @cindex @code{Excluded_Source_Dirs}
275 When using that construct, it can sometimes be convenient to also use the
276 attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry
277 specifies a directory whose immediate content, not including subdirs, is to
278 be excluded. It is also possible to exclude a complete directory subtree
279 using the "/**" notation.
284 When applied to the simple example, and because we generally prefer to have
285 the project file at the toplevel directory rather than mixed with the sources,
286 we will create the following file
290 @b{project} Build @b{is}
291 @b{for} Source_Dirs @b{use} ("common"); -- <<<<
296 Once source directories have been specified, one may need to indicate
297 source files of interest. By default, all source files present in the source
298 directories are considered by the project manager. When this is not desired,
299 it is possible to specify the list of sources to consider explicitly.
300 In such a case, only source file base names are indicated and not
301 their absolute or relative path names. The project manager is in charge of
302 locating the specified source files in the specified source directories.
305 @item By default, the project manager search for all source files of all
306 specified languages in all the source directories.
308 Since the project manager was initially developed for Ada environments, the
309 default language is usually Ada and the above project file is complete: it
310 defines without ambiguity the sources composing the project: that is to say,
311 all the sources in subdirectory "common" for the default language (Ada) using
312 the default naming convention.
314 @cindex @code{Languages}
315 However, when compiling a multi-language application, or a pure C
316 application, the project manager must be told which languages are of
317 interest, which is done by setting the @b{Languages} attribute to a list of
318 strings, each of which is the name of a language. Tools like
319 @command{gnatmake} only know about Ada, while other tools like
320 @command{gprbuild} know about many more languages such as C, C++, Fortran,
321 assembly and others can be added dynamically.
323 @cindex Naming scheme
324 Even when using only Ada, the default naming might not be suitable. Indeed,
325 how does the project manager recognizes an "Ada file" from any other
326 file? Project files can describe the naming scheme used for source files,
327 and override the default (@pxref{Naming Schemes}). The default is the
328 standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
329 specs), which is what is used in our example, explaining why no naming scheme
330 is explicitly specified.
331 @xref{Naming Schemes}.
333 @item @code{Source Files}
334 @cindex @code{Source_Files}
335 In some cases, source directories might contain files that should not be
336 included in a project. One can specify the explicit list of file names to
337 be considered through the @b{Source_Files} attribute.
338 When this attribute is defined, instead of looking at every file in the
339 source directories, the project manager takes only those names into
340 consideration reports errors if they cannot be found in the source
341 directories or does not correspond to the naming scheme.
343 @item For various reasons, it is sometimes useful to have a project with no
344 sources (most of the time because the attributes defined in the project
345 file will be reused in other projects, as explained in @pxref{Organizing
346 Projects into Subsystems}. To do this, the attribute
347 @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
348 @emph{Source_Dirs} can be set to the empty list, with the same
351 @item @code{Source_List_File}
352 @cindex @code{Source_List_File}
353 If there is a great number of files, it might be more convenient to use
354 the attribute @b{Source_List_File}, which specifies the full path of a file.
355 This file must contain a list of source file names (one per line, no
356 directory information) that are searched as if they had been defined
357 through @emph{Source_Files}. Such a file can easily be created through
360 A warning is issued if both attributes @code{Source_Files} and
361 @code{Source_List_File} are given explicit values. In this case, the
362 attribute @code{Source_Files} prevails.
364 @item @code{Excluded_Source_Files}
365 @cindex @code{Excluded_Source_Files}
366 @cindex @code{Locally_Removed_Files}
367 @cindex @code{Excluded_Source_List_File}
368 Specifying an explicit list of files is not always convenient.It might be
369 more convenient to use the default search rules with specific exceptions.
370 This can be done thanks to the attribute @b{Excluded_Source_Files}
371 (or its synonym @b{Locally_Removed_Files}).
372 Its value is the list of file names that should not be taken into account.
373 This attribute is often used when extending a project, @xref{Project
374 Extension}. A similar attribute @b{Excluded_Source_List_File} plays the same
375 role but takes the name of file containing file names similarly to
376 @code{Source_List_File}.
381 In most simple cases, such as the above example, the default source file search
382 behavior provides the expected result, and we do not need to add anything after
383 setting @code{Source_Dirs}. The project manager automatically finds
384 @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the
387 Note that it is considered an error for a project file to have no sources
388 attached to it unless explicitly declared as mentionend above.
390 If the order of the source directories is known statically, that is if
391 @code{"/**"} is not used in the string list @code{Source_Dirs}, then there may
392 be several files with the same source file name sitting in different
393 directories of the project. In this case, only the file in the first directory
394 is considered as a source of the project and the others are hidden. If
395 @code{"/**"} is not used in the string list @code{Source_Dirs}, it is an error
396 to have several files with the same source file name in the same directory
397 @code{"/**"} subtree, since there would be an ambiguity as to which one should
398 be used. However, two files with the same source file name may in two single
399 directories or directory subtrees. In this case, the one in the first directory
400 or directory subtree is a source of the project.
402 @c ---------------------------------------------
403 @node Object and Exec Directory
404 @subsection Object and Exec Directory
405 @c ---------------------------------------------
408 The next step when writing a project is to indicate where the compiler should
409 put the object files. In fact, the compiler and other tools might create
410 several different kind of files (for GNAT, there is the object file and the ALI
411 file for instance). One of the important concepts in projects is that most
412 tools may consider source directories as read-only and do not attempt to create
413 new or temporary files there. Instead, all files are created in the object
414 directory. It is of course not true for project-aware IDEs, whose purpose it is
415 to create the source files.
417 @cindex @code{Object_Dir}
418 The object directory is specified through the @b{Object_Dir} attribute.
419 Its value is the path to the object directory, either absolute or
420 relative to the directory containing the project file. This
421 directory must already exist and be readable and writable, although
422 some tools have a switch to create the directory if needed (See
423 the switch @code{-p} for @command{gnatmake} and @command{gprbuild}).
425 If the attribute @code{Object_Dir} is not specified, it defaults to
426 the project directory, that is the directory containing the project file.
428 For our example, we can specify the object dir in this way:
431 @b{project} Build @b{is}
432 @b{for} Source_Dirs @b{use} ("common");
433 @b{for} Object_Dir @b{use} "obj"; -- <<<<
438 As mentioned earlier, there is a single object directory per project. As a
439 result, if you have an existing system where the object files are spread in
440 several directories, you can either move all of them into the same directory if
441 you want to build it with a single project file, or study the section on
442 subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
443 separate object directory can be associated with one of the subsystem
444 constituting the application.
446 When the @command{linker} is called, it usually creates an executable. By
447 default, this executable is placed in the object directory of the project. It
448 might be convenient to store it in its own directory.
450 @cindex @code{Exec_Dir}
451 This can be done through the @code{Exec_Dir} attribute, which, like
452 @emph{Object_Dir} contains a single absolute or relative path and must point to
453 an existing and writable directory, unless you ask the tool to create it on
454 your behalf. When not specified, It defaults to the object directory and
455 therefore to the project file's directory if neither @emph{Object_Dir} nor
456 @emph{Exec_Dir} was specified.
458 In the case of the example, let's place the executable in the root
459 of the hierarchy, ie the same directory as @file{build.gpr}. Hence
460 the project file is now
463 @b{project} Build @b{is}
464 @b{for} Source_Dirs @b{use} ("common");
465 @b{for} Object_Dir @b{use} "obj";
466 @b{for} Exec_Dir @b{use} "."; -- <<<<
470 @c ---------------------------------------------
471 @node Main Subprograms
472 @subsection Main Subprograms
473 @c ---------------------------------------------
476 In the previous section, executables were mentioned. The project manager needs
477 to be taught what they are. In a project file, an executable is indicated by
478 pointing to source file of the main subprogram. In C this is the file that
479 contains the @code{main} function, and in Ada the file that contains the main
482 There can be any number of such main files within a given project, and thus
483 several executables can be built in the context of a single project file. Of
484 course, one given executable might not (and in fact will not) need all the
485 source files referenced by the project. As opposed to other build environments
486 such as @command{makefile}, one does not need to specify the list of
487 dependencies of each executable, the project-aware builders knows enough of the
488 semantics of the languages to build ands link only the necessary elements.
491 The list of main files is specified via the @b{Main} attribute. It contains
492 a list of file names (no directories). If a project defines this
493 attribute, it is not necessary to identify main files on the
494 command line when invoking a builder, and editors like
495 @command{GPS} will be able to create extra menus to spawn or debug the
496 corresponding executables.
499 @b{project} Build @b{is}
500 @b{for} Source_Dirs @b{use} ("common");
501 @b{for} Object_Dir @b{use} "obj";
502 @b{for} Exec_Dir @b{use} ".";
503 @b{for} Main @b{use} ("proc.adb"); -- <<<<
508 If this attribute is defined in the project, then spawning the builder
509 with a command such as
512 gnatmake ^-Pbuild^/PROJECT_FILE=build^
516 automatically builds all the executables corresponding to the files
517 listed in the @emph{Main} attribute. It is possible to specify one
518 or more executables on the command line to build a subset of them.
520 @c ---------------------------------------------
521 @node Tools Options in Project Files
522 @subsection Tools Options in Project Files
523 @c ---------------------------------------------
526 We now have a project file that fully describes our environment, and can be
527 used to build the application with a simple @command{gnatmake} command as seen
528 in the previous section. In fact, the empty project we showed immediately at
529 the beginning (with no attribute at all) could already fullfill that need if it
530 was put in the @file{common} directory.
532 Of course, we always want more control. This section will show you how to
533 specify the compilation switches that the various tools involved in the
534 building of the executable should use.
536 @cindex command line length
537 Since source names and locations are described into the project file, it is not
538 necessary to use switches on the command line for this purpose (switches such
539 as -I for gcc). This removes a major source of command line length overflow.
540 Clearly, the builders will have to communicate this information one way or
541 another to the underlying compilers and tools they call but they usually use
542 response files for this and thus should not be subject to command line
545 Several tools are participating to the creation of an executable: the compiler
546 produces object files from the source files; the binder (in the Ada case)
547 creates an source file that takes care, among other things, of elaboration
548 issues and global variables initialization; and the linker gathers everything
549 into a single executable that users can execute. All these tools are known by
550 the project manager and will be called with user defined switches from the
551 project files. However, we need to introduce a new project file concept to
552 express which switches to be used for any of the tools involved in the build.
554 @cindex project file packages
555 A project file is subdivided into zero or more @b{packages}, each of which
556 contains the attributes specific to one tool (or one set of tools). Project
557 files use an Ada-like syntax for packages. Package names permitted in project
558 files are restricted to a predefined set (@pxref{Packages}), and the contents
559 of packages are limited to a small set of constructs and attributes
560 (@pxref{Attributes}).
562 Our example project file can be extended with the following empty packages. At
563 this stage, they could all be omitted since they are empty, but they show which
564 packages would be involved in the build process.
567 @b{project} Build @b{is}
568 @b{for} Source_Dirs @b{use} ("common");
569 @b{for} Object_Dir @b{use} "obj";
570 @b{for} Exec_Dir @b{use} ".";
571 @b{for} Main @b{use} ("proc.adb");
574 @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
577 @b{package} Compiler @b{is} --<<< for the compiler
580 @b{package} Binder @b{is} --<<< for the binder
583 @b{package} Linker @b{is} --<<< for the linker
588 Let's first examine the compiler switches. As stated in the initial description
589 of the example, we want to compile all files with @option{-O2}. This is a
590 compiler switch, although it is usual, on the command line, to pass it to the
591 builder which then passes it to the compiler. It is recommended to use directly
592 the right package, which will make the setup easier to understand for other
595 Several attributes can be used to specify the switches:
598 @item @b{Default_Switches}:
599 @cindex @code{Default_Switches}
600 This is the first mention in this manual of an @b{indexed attribute}. When
601 this attribute is defined, one must supply an @emph{index} in the form of a
603 In the case of @emph{Default_Switches}, the index is the name of the
604 language to which the switches apply (since a different compiler will
605 likely be used for each language, and each compiler has its own set of
606 switches). The value of the attribute is a list of switches.
608 In this example, we want to compile all Ada source files with the
609 @option{-O2} switch, and the resulting project file is as follows
610 (only the @code{Compiler} package is shown):
613 @b{package} Compiler @b{is}
614 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
619 @cindex @code{Switches}
620 in some cases, we might want to use specific switches
621 for one or more files. For instance, compiling @file{proc.adb} might not be
622 possible at high level of optimization because of a compiler issue.
623 In such a case, the @emph{Switches}
624 attribute (indexed on the file name) can be used and will override the
625 switches defined by @emph{Default_Switches}. Our project file would
629 @b{package} Compiler @b{is}
630 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
631 @b{for} Switches ("proc.adb") @b{use} ("-O0");
636 @code{Switches} can also be given a language name as index instead of a file
637 name in which case it has the same semantics as @emph{Default_Switches}.
639 @item @b{Local_Configuration_Pragmas}:
640 @cindex @code{Local_Configuration_Pragmas}
641 this attribute may specify the path
642 of a file containing configuration pragmas for use by the Ada compiler,
643 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
644 used for all the sources of the project.
648 The switches for the other tools are defined in a similar manner through the
649 @b{Default_Switches} and @b{Switches} attributes, respectively in the
650 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
651 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
652 package (for linking executables).
654 @c ---------------------------------------------
655 @node Compiling with Project Files
656 @subsection Compiling with Project Files
657 @c ---------------------------------------------
660 Now that our project files are written, let's build our executable.
661 Here is the command we would use from the command line:
664 gnatmake ^-Pbuild^/PROJECT_FILE=build^
668 This will automatically build the executables specified through the
669 @emph{Main} attribute: for each, it will compile or recompile the
670 sources for which the object file does not exist or is not up-to-date; it
671 will then run the binder; and finally run the linker to create the
674 @command{gnatmake} only knows how to handle Ada files. By using
675 @command{gprbuild} as a builder, you could automatically manage C files the
676 same way: create the file @file{utils.c} in the @file{common} directory,
677 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
680 gprbuild ^-Pbuild^/PROJECT_FILE=build^
684 Gprbuild knows how to recompile the C files and will
685 recompile them only if one of their dependencies has changed. No direct
686 indication on how to build the various elements is given in the
687 project file, which describes the project properties rather than a
688 set of actions to be executed. Here is the invocation of
689 @command{gprbuild} when building a multi-language program:
702 Notice the three steps described earlier:
705 @item The first three gcc commands correspond to the compilation phase.
706 @item The gprbind command corresponds to the post-compilation phase.
707 @item The last gcc command corresponds to the final link.
712 @cindex @option{-v} option (for GPRbuild)
713 The default output of GPRbuild's execution is kept reasonably simple and easy
714 to understand. In particular, some of the less frequently used commands are not
715 shown, and some parameters are abbreviated. So it is not possible to rerun the
716 effect ofthe gprbuild command by cut-and-pasting its output. GPRbuild's option
717 @code{-v} provides a much more verbose output which includes, among other
718 information, more complete compilation, post-compilation and link commands.
720 @c ---------------------------------------------
721 @node Executable File Names
722 @subsection Executable File Names
723 @c ---------------------------------------------
726 @cindex @code{Executable}
727 By default, the executable name corresponding to a main file is
728 computed from the main source file name. Through the attribute
729 @b{Builder.Executable}, it is possible to change this default.
731 For instance, instead of building @command{proc} (or @command{proc.exe}
732 on Windows), we could configure our project file to build "proc1"
733 (resp proc1.exe) with the following addition:
735 @smallexample @c projectfile
737 ... -- same as before
739 for Executable ("proc.adb") use "proc1";
745 @cindex @code{Executable_Suffix}
746 Attribute @b{Executable_Suffix}, when specified, may change the suffix
747 of the executable files, when no attribute @code{Executable} applies:
748 its value replace the platform-specific executable suffix.
749 The default executable suffix is empty on UNIX and ".exe" on Windows.
751 It is also possible to change the name of the produced executable by using the
752 command line switch @option{-o}. When several mains are defined in the project,
753 it is not possible to use the @option{-o} switch and the only way to change the
754 names of the executable is provided by Attributes @code{Executable} and
755 @code{Executable_Suffix}.
757 @c ---------------------------------------------
758 @node Avoid Duplication With Variables
759 @subsection Avoid Duplication With Variables
760 @c ---------------------------------------------
763 To illustrate some other project capabilities, here is a slightly more complex
764 project using similar sources and a main program in C:
766 @smallexample @c projectfile
768 for Languages use ("Ada", "C");
769 for Source_Dirs use ("common");
770 for Object_Dir use "obj";
771 for Main use ("main.c");
773 C_Switches := ("-pedantic");
774 for Default_Switches ("C") use C_Switches;
775 for Default_Switches ("Ada") use ("-gnaty");
776 for Switches ("main.c") use C_Switches & ("-g");
782 This project has many similarities with the previous one.
783 As expected, its @code{Main} attribute now refers to a C source.
784 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
785 executable will be put in the directory @file{obj}.
787 The most noticeable difference is the use of a variable in the
788 @emph{Compiler} package to store settings used in several attributes.
789 This avoids text duplication, and eases maintenance (a single place to
790 modify if we want to add new switches for C files). We will revisit
791 the use of variables in the context of scenarios (@pxref{Scenarios in
794 In this example, we see how the file @file{main.c} can be compiled with
795 the switches used for all the other C files, plus @option{-g}.
796 In this specific situation the use of a variable could have been
797 replaced by a reference to the @code{Default_Switches} attribute:
799 @smallexample @c projectfile
800 for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
804 Note the tick (@emph{'}) used to refer to attributes defined in a package.
806 Here is the output of the GPRbuild command using this project:
810 gcc -c -pedantic -g main.c
811 gcc -c -gnaty proc.adb
812 gcc -c -gnaty pack.adb
813 gcc -c -pedantic utils.c
820 The default switches for Ada sources,
821 the default switches for C sources (in the compilation of @file{lib.c}),
822 and the specific switches for @file{main.c} have all been taken into
825 @c ---------------------------------------------
827 @subsection Naming Schemes
828 @c ---------------------------------------------
831 Sometimes an Ada software system is ported from one compilation environment to
832 another (say GNAT), and the file are not named using the default GNAT
833 conventions. Instead of changing all the file names, which for a variety of
834 reasons might not be possible, you can define the relevant file naming scheme
835 in the @b{Naming} package of your project file.
837 The naming scheme has two distinct goals for the project manager: it
838 allows finding of source files when searching in the source
839 directories, and given a source file name it makes it possible to guess
840 the associated language, and thus the compiler to use.
842 Note that the use by the Ada compiler of pragmas Source_File_Name is not
843 supported when using project files. You must use the features described in this
844 paragraph. You can however specify other configuration pragmas
845 (@pxref{Specifying Configuration Pragmas}).
847 The following attributes can be defined in package @code{Naming}:
851 @cindex @code{Casing}
852 Its value must be one of @code{"lowercase"} (the default if
853 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
854 casing of file names with regards to the Ada unit name. Given an Ada unit
855 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
856 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
857 On Windows, file names are case insensitive, so this attribute is
860 @item @b{Dot_Replacement}:
861 @cindex @code{Dot_Replacement}
862 This attribute specifies the string that should replace the "." in unit
863 names. Its default value is @code{"-"} so that a unit
864 @code{Parent.Child} is expected to be found in the file
865 @file{parent-child.adb}. The replacement string must satisfy the following
866 requirements to avoid ambiguities in the naming scheme:
869 @item It must not be empty
870 @item It cannot start or end with an alphanumeric character
871 @item It cannot be a single underscore
872 @item It cannot start with an underscore followed by an alphanumeric
873 @item It cannot contain a dot @code{'.'} except if the entire string
878 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
879 @cindex @code{Spec_Suffix}
880 @cindex @code{Specification_Suffix}
881 For Ada, these attributes give the suffix used in file names that contain
882 specifications. For other languages, they give the extension for files
883 that contain declaration (header files in C for instance). The attribute
884 is indexed on the language.
885 The two attributes are equivalent, but the latter is obsolescent.
886 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
887 @code{"^.ads^.ADS^"}.
888 The value must satisfy the following requirements:
891 @item It must not be empty
892 @item It cannot start with an alphanumeric character
893 @item It cannot start with an underscore followed by an alphanumeric character
894 @item It must include at least one dot
898 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
899 @cindex @code{Body_Suffix}
900 @cindex @code{Implementation_Suffix}
901 These attributes give the extension used for file names that contain
902 code (bodies in Ada). They are indexed on the language. The second
903 version is obsolescent and fully replaced by the first attribute.
905 These attributes must satisfy the same requirements as @code{Spec_Suffix}.
906 In addition, they must be different from any of the values in
908 If @code{Body_Suffix ("Ada")} is not specified, then the default is
909 @code{"^.adb^.ADB^"}.
911 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
912 same string, then a file name that ends with the longest of these two
913 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
914 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
916 If the suffix does not start with a '.', a file with a name exactly equal
917 to the suffix will also be part of the project (for instance if you define
918 the suffix as @code{Makefile}, a file called @file{Makefile} will be part
919 of the project. This capability is usually not interesting when building.
920 However, it might become useful when a project is also used to
921 find the list of source files in an editor, like the GNAT Programming System
924 @item @b{Separate_Suffix}:
925 @cindex @code{Separate_Suffix}
926 This attribute is specific to Ada. It denotes the suffix used in file names
927 that contain separate bodies. If it is not specified, then it defaults to
928 same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the
929 @code{Body_Suffix} attribute. The only accepted index is "Ada".
931 @item @b{Spec} or @b{Specification}:
933 @cindex @code{Specification}
934 This attribute @code{Spec} can be used to define the source file name for a
935 given Ada compilation unit's spec. The index is the literal name of the Ada
936 unit (case insensitive). The value is the literal base name of the file that
937 contains this unit's spec (case sensitive or insensitive depending on the
938 operating system). This attribute allows the definition of exceptions to the
939 general naming scheme, in case some files do not follow the usual
942 When a source file contains several units, the relative position of the unit
943 can be indicated. The first unit in the file is at position 1
945 @smallexample @c projectfile
946 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
947 for Spec ("top") use "foo.a" at 1;
948 for Spec ("foo") use "foo.a" at 2;
951 @item @b{Body} or @b{Implementation}:
953 @cindex @code{Implementation}
954 These attribute play the same role as @emph{Spec} for Ada bodies.
956 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
957 @cindex @code{Specification_Exceptions}
958 @cindex @code{Implementation_Exceptions}
959 These attributes define exceptions to the naming scheme for languages
960 other than Ada. They are indexed on the language name, and contain
961 a list of file names respectively for headers and source code.
967 For example, the following package models the Apex file naming rules:
969 @smallexample @c projectfile
972 for Casing use "lowercase";
973 for Dot_Replacement use ".";
974 for Spec_Suffix ("Ada") use ".1.ada";
975 for Body_Suffix ("Ada") use ".2.ada";
982 For example, the following package models the DEC Ada file naming rules:
984 @smallexample @c projectfile
987 for Casing use "lowercase";
988 for Dot_Replacement use "__";
989 for Spec_Suffix ("Ada") use "_.ada";
990 for Body_Suffix ("Ada") use ".ada";
996 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1000 @c ---------------------------------------------
1001 @node Organizing Projects into Subsystems
1002 @section Organizing Projects into Subsystems
1003 @c ---------------------------------------------
1006 A @b{subsystem} is a coherent part of the complete system to be built. It is
1007 represented by a set of sources and one single object directory. A system can
1008 be composed of a single subsystem when it is simple as we have seen in the
1009 first section. Complex systems are usually composed of several interdependent
1010 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1011 other one is required to build it, and in particular if visibility on some of
1012 the sources of this other subsystem is required. Each subsystem is usually
1013 represented by its own project file.
1015 In this section, the previous example is being extended. Let's assume some
1016 sources of our @code{Build} project depend on other sources.
1017 For instance, when building a graphical interface, it is usual to depend upon
1018 a graphical library toolkit such as GtkAda. Furthermore, we also need
1019 sources from a logging module we had previously written.
1022 * Project Dependencies::
1023 * Cyclic Project Dependencies::
1024 * Sharing Between Projects::
1025 * Global Attributes::
1028 @c ---------------------------------------------
1029 @node Project Dependencies
1030 @subsection Project Dependencies
1031 @c ---------------------------------------------
1034 GtkAda comes with its own project file (appropriately called
1035 @file{gtkada.gpr}), and we will assume we have already built a project
1036 called @file{logging.gpr} for the logging module. With the information provided
1037 so far in @file{build.gpr}, building the application would fail with an error
1038 indicating that the gtkada and logging units that are relied upon by the sources
1039 of this project cannot be found.
1041 This is easily solved by adding the following @b{with} clauses at the beginning
1044 @smallexample @c projectfile
1046 with "a/b/logging.gpr";
1053 @cindex @code{Externally_Built}
1054 When such a project is compiled, @command{gnatmake} will automatically
1055 check the other projects and recompile their sources when needed. It will also
1056 recompile the sources from @code{Build} when needed, and finally create the
1057 executable. In some cases, the implementation units needed to recompile a
1058 project are not available, or come from some third-party and you do not want to
1059 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1060 "true" can be set, indicating to the builder that this project can be assumed
1061 to be up-to-date, and should not be considered for recompilation. In Ada, if
1062 the sources of this externally built project were compiled with another version
1063 of the compiler or with incompatible options, the binder will issue an error.
1065 The project's @code{with} clause has several effects. It provides source
1066 visibility between projects during the compilation process. It also guarantees
1067 that the necessary object files from @code{Logging} and @code{GtkAda} are
1068 available when linking @code{Build}.
1070 As can be seen in this example, the syntax for importing projects is similar
1071 to the syntax for importing compilation units in Ada. However, project files
1072 use literal strings instead of names, and the @code{with} clause identifies
1073 project files rather than packages.
1075 Each literal string after @code{with} is the path
1076 (absolute or relative) to a project file. The @code{.gpr} extension is
1077 optional, although we recommend adding it. If no extension is specified,
1078 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1079 the file is searched for exactly as written in the @code{with} clause,
1080 that is with no extension.
1082 @cindex project path
1083 When a relative path or a base name is used, the
1084 project files are searched relative to each of the directories in the
1085 @b{project path}. This path includes all the directories found with the
1086 following algorithm, in that order, as soon as a matching file is found,
1090 @item First, the file is searched relative to the directory that contains the
1091 current project file.
1093 @cindex @code{ADA_PROJECT_PATH}
1094 @cindex @code{GPR_PROJECT_PATH}
1095 Then it is searched relative to all the directories specified in the
1096 ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and
1097 @b{ADA_PROJECT_PATH} (in that order) if they exist. The former is
1098 recommended, the latter is kept for backward compatibility.
1099 @item Finally, it is searched relative to the default project directories.
1100 Such directories depends on the tool used. For @command{gnatmake}, there is
1101 one default project directory: @file{<prefix>/lib/gnat/}. In our example,
1102 @file{gtkada.gpr} is found in the predefined directory if it was installed at
1103 the same root as GNAT.
1108 Some tools also support extending the project path from the command line,
1109 generally through the @option{-aP}. You can see the value of the project
1110 path by using the @command{gnatls -v} command.
1112 Any symbolic link will be fully resolved in the directory of the
1113 importing project file before the imported project file is examined.
1115 Any source file in the imported project can be used by the sources of the
1116 importing project, transitively.
1117 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1118 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1119 import @code{C} explicitly. However, this is not recommended, because if
1120 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1121 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1122 that will report such indirect dependencies.
1124 One very important aspect of a project hierarchy is that
1125 @b{a given source can only belong to one project} (otherwise the project manager
1126 would not know which settings apply to it and when to recompile it). It means
1127 that different project files do not usually share source directories or
1128 when they do, they need to specify precisely which project owns which sources
1129 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1130 can each own a source with the same base file name as long as they live in
1131 different directories. The latter is not true for Ada Sources because of the
1132 correlation betwen source files and Ada units.
1134 @c ---------------------------------------------
1135 @node Cyclic Project Dependencies
1136 @subsection Cyclic Project Dependencies
1137 @c ---------------------------------------------
1140 Cyclic dependencies are mostly forbidden:
1141 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1142 is not allowed to import @code{A}. However, there are cases when cyclic
1143 dependencies would be beneficial. For these cases, another form of import
1144 between projects exists: the @b{limited with}. A project @code{A} that
1145 imports a project @code{B} with a straight @code{with} may also be imported,
1146 directly or indirectly, by @code{B} through a @code{limited with}.
1148 The difference between straight @code{with} and @code{limited with} is that
1149 the name of a project imported with a @code{limited with} cannot be used in the
1150 project importing it. In particular, its packages cannot be renamed and
1151 its variables cannot be referred to.
1153 @smallexample @c 0projectfile
1157 For Exec_Dir use B'Exec_Dir; -- ok
1160 limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
1162 For Exec_Dir use A'Exec_Dir; -- not ok
1169 limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
1171 For Exec_Dir use A'Exec_Dir; -- not ok
1175 @c ---------------------------------------------
1176 @node Sharing Between Projects
1177 @subsection Sharing Between Projects
1178 @c ---------------------------------------------
1181 When building an application, it is common to have similar needs in severa of
1182 the projects corresponding to the subsystems under construction. For instance,
1183 they will all have the same compilation switches.
1185 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1186 switches for all sources of a subsystem is simple: it is just a matter of
1187 adding a @code{Compiler.Default_Switches} attribute to each project files with
1188 the same value. Of course, that means duplication of data, and both places need
1189 to be changed in order to recompile the whole application with different
1190 switches. It can become a real problem if there are many subsystems and thus
1191 many project files to edit.
1193 There are two main approaches to avoiding this duplication:
1196 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1197 to reference the attribute in Logging, either through a package renaming,
1198 or by referencing the attribute. The following example shows both cases:
1200 @smallexample @c projectfile
1203 for Switches ("Ada") use ("-O2");
1206 for Switches ("Ada") use ("-E");
1212 package Compiler renames Logging.Compiler;
1214 for Switches ("Ada") use Logging.Binder'Switches ("Ada");
1220 The solution used for @code{Compiler} gets the same value for all
1221 attributes of the package, but you cannot modify anything from the
1222 package (adding extra switches or some exceptions). The second
1223 version is more flexible, but more verbose.
1225 If you need to refer to the value of a variable in an imported
1226 project, rather than an attribute, the syntax is similar but uses
1227 a "." rather than an apostrophe. For instance:
1229 @smallexample @c projectfile
1232 Var1 := Imported.Var;
1236 @item The second approach is to define the switches in a third project.
1237 That project is setup without any sources (so that, as opposed to
1238 the first example, none of the project plays a special role), and
1239 will only be used to define the attributes. Such a project is
1240 typically called @file{shared.gpr}.
1242 @smallexample @c projectfile
1243 abstract project Shared is
1244 for Source_Files use (); -- no project
1246 for Switches ("Ada") use ("-O2");
1252 package Compiler renames Shared.Compiler;
1257 package Compiler renames Shared.Compiler;
1262 As for the first example, we could have chosen to set the attributes
1263 one by one rather than to rename a package. The reason we explicitly
1264 indicate that @code{Shared} has no sources is so that it can be created
1265 in any directory and we are sure it shares no sources with @code{Build}
1266 or @code{Logging}, which of course would be invalid.
1268 @cindex project qualifier
1269 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1270 This qualifier is optional, but helps convey the message that we do not
1271 intend this project to have sources (@pxref{Qualified Projects} for
1276 @c ---------------------------------------------
1277 @node Global Attributes
1278 @subsection Global Attributes
1279 @c ---------------------------------------------
1282 We have already seen many examples of attributes used to specify a special
1283 option of one of the tools involved in the build process. Most of those
1284 attributes are project specific. That it to say, they only affect the invocation
1285 of tools on the sources of the project where they are defined.
1287 There are a few additional attributes that apply to all projects in a
1288 hierarchy as long as they are defined on the "main" project.
1289 The main project is the project explicitly mentioned on the command-line.
1290 The project hierarchy is the "with"-closure of the main project.
1292 Here is a list of commonly used global attributes:
1295 @item @b{Builder.Global_Configuration_Pragmas}:
1296 @cindex @code{Global_Configuration_Pragmas}
1297 This attribute points to a file that contains configuration pragmas
1298 to use when building executables. These pragmas apply for all
1299 executables build from this project hierarchy. As we have seen before,
1300 additional pragmas can be specified on a per-project basis by setting the
1301 @code{Compiler.Local_Configuration_Pragmas} attribute.
1303 @item @b{Builder.Global_Compilation_Switches}:
1304 @cindex @code{Global_Compilation_Switches}
1305 This attribute is a list of compiler switches to use when compiling any
1306 source file in the project hierarchy. These switches are used in addition
1307 to the ones defined in the @code{Compiler} package, which only apply to
1308 the sources of the corresponding project. This attribute is indexed on
1309 the name of the language.
1313 Using such global capabilities is convenient. It can also lead to unexpected
1314 behavior. Especially when several subsystems are shared among different main
1315 projects and the different global attributes are not
1316 compatible. Note that using aggregate projects can be a safer and more powerful
1317 replacement to global attributes.
1319 @c ---------------------------------------------
1320 @node Scenarios in Projects
1321 @section Scenarios in Projects
1322 @c ---------------------------------------------
1325 Various aspects of the projects can be modified based on @b{scenarios}. These
1326 are user-defined modes that change the behavior of a project. Typical
1327 examples are the setup of platform-specific compiler options, or the use of
1328 a debug and a release mode (the former would activate the generation of debug
1329 information, when the second will focus on improving code optimization).
1331 Let's enhance our example to support a debug and a release modes.The issue is to
1332 let the user choose what kind of system he is building:
1333 use @option{-g} as compiler switches in debug mode and @option{-O2}
1334 in release mode. We will also setup the projects so that we do not share the
1335 same object directory in both modes, otherwise switching from one to the other
1336 might trigger more recompilations than needed or mix objects from the 2 modes.
1338 One naive approach is to create two different project files, say
1339 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1340 attributes as explained in previous sections. This solution does not scale well,
1341 because in presence of multiple projects depending on each other,
1342 you will also have to duplicate the complete hierarchy and adapt the project
1343 files to point to the right copies.
1346 Instead, project files support the notion of scenarios controlled
1347 by external values. Such values can come from several sources (in decreasing
1351 @item @b{Command line}:
1353 When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1354 extra @option{-X} switches to define the external value. In
1355 our case, the command line might look like
1358 gnatmake -Pbuild.gpr -Xmode=debug
1359 or gnatmake -Pbuild.gpr -Xmode=release
1362 @item @b{^Environment variables^Logical names^}:
1363 When the external value does not come from the command line, it can come from
1364 the value of ^environment variables^logical names^ of the appropriate name.
1365 In our case, if ^an environment variable^a logical name^ called "mode"
1366 exist, its value will be taken into account.
1368 @item @b{External function second parameter}
1372 @cindex @code{external}
1373 We now need to get that value in the project. The general form is to use
1374 the predefined function @b{external} which returns the current value of
1375 the external. For instance, we could setup the object directory to point to
1376 either @file{obj/debug} or @file{obj/release} by changing our project to
1378 @smallexample @c projectfile
1380 for Object_Dir use "obj/" & external ("mode", "debug");
1386 The second parameter to @code{external} is optional, and is the default
1387 value to use if "mode" is not set from the command line or the environment.
1389 In order to set the switches according to the different scenarios, other
1390 constructs have to be introduced such as typed variables and case statements.
1392 @cindex typed variable
1393 @cindex case statement
1394 A @b{typed variable} is a variable that
1395 can take only a limited number of values, similar to an enumeration in Ada.
1396 Such a variable can then be used in a @b{case statement} and create conditional
1397 sections in the project. The following example shows how this can be done:
1399 @smallexample @c projectfile
1401 type Mode_Type is ("debug", "release"); -- all possible values
1402 Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1407 for Switches ("Ada") use ("-g");
1409 for Switches ("Ada") use ("-O2");
1416 The project has suddenly grown in size, but has become much more flexible.
1417 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1418 any other value is read from the environment, an error is reported and the
1419 project is considered as invalid.
1421 The @code{Mode} variable is initialized with an external value
1422 defaulting to @code{"debug"}. This default could be omitted and that would
1423 force the user to define the value. Finally, we can use a case statement to set the
1424 switches depending on the scenario the user has chosen.
1426 Most aspects of the projects can depend on scenarios. The notable exception
1427 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1429 Scenarios work the same way with @b{project hierarchies}: you can either
1430 duplicate a variable similar to @code{Mode} in each of the project (as long
1431 as the first argument to @code{external} is always the same and the type is
1432 the same), or simply set the variable in the @file{shared.gpr} project
1433 (@pxref{Sharing Between Projects}).
1435 @c ---------------------------------------------
1436 @node Library Projects
1437 @section Library Projects
1438 @c ---------------------------------------------
1441 So far, we have seen examples of projects that create executables. However,
1442 it is also possible to create libraries instead. A @b{library} is a specific
1443 type of subsystem where, for convenience, objects are grouped together
1444 using system-specific means such as archives or windows DLLs.
1446 Library projects provide a system- and language-independent way of building both @b{static}
1447 and @b{dynamic} libraries. They also support the concept of @b{standalone
1448 libraries} (SAL) which offers two significant properties: the elaboration
1449 (e.g. initialization) of the library is either automatic or very simple;
1451 implementation part of the library implies minimal post-compilation actions on
1452 the complete system and potentially no action at all for the rest of the
1453 system in the case of dynamic SALs.
1455 The GNAT Project Manager takes complete care of the library build, rebuild and
1456 installation tasks, including recompilation of the source files for which
1457 objects do not exist or are not up to date, assembly of the library archive, and
1458 installation of the library (i.e., copying associated source, object and
1459 @file{ALI} files to the specified location).
1462 * Building Libraries::
1463 * Using Library Projects::
1464 * Stand-alone Library Projects::
1465 * Installing a library with project files::
1468 @c ---------------------------------------------
1469 @node Building Libraries
1470 @subsection Building Libraries
1471 @c ---------------------------------------------
1474 Let's enhance our example and transform the @code{logging} subsystem into a
1475 library.In orer to do so, a few changes need to be made to @file{logging.gpr}.
1476 A number of specific attributes needs to be defined: at least @code{Library_Name}
1477 and @code{Library_Dir}; in addition, a number of other attributes can be used
1478 to specify specific aspects of the library. For readablility, it is also
1479 recommended (although not mandatory), to use the qualifier @code{library} in
1480 front of the @code{project} keyword.
1483 @item @b{Library_Name}:
1484 @cindex @code{Library_Name}
1485 This attribute is the name of the library to be built. There is no
1486 restriction on the name of a library imposed by the project manager;
1487 however, there may be system specific restrictions on the name.
1488 In general, it is recommended to stick to alphanumeric characters
1489 (and possibly underscores) to help portability.
1491 @item @b{Library_Dir}:
1492 @cindex @code{Library_Dir}
1493 This attribute is the path (absolute or relative) of the directory where
1494 the library is to be installed. In the process of building a library,
1495 the sources are compiled, the object files end up in the explicit or
1496 implicit @code{Object_Dir} directory. When all sources of a library
1497 are compiled, some of the compilation artifacts, including the library itself,
1498 are copied to the library_dir directory. This directory must exists and be
1499 writable. It must also be different from the object directory so that cleanup
1500 activities in the Library_Dir do not affect recompilation needs.
1504 Here is the new version of @file{logging.gpr} that makes it a library:
1506 @smallexample @c projectfile
1507 library project Logging is -- "library" is optional
1508 for Library_Name use "logging"; -- will create "liblogging.a" on Unix
1509 for Object_Dir use "obj";
1510 for Library_Dir use "lib"; -- different from object_dir
1515 Once the above two attributes are defined, the library project is valid and
1516 is enough for building a library with default characteristics.
1517 Other library-related attributes can be used to change the defaults:
1520 @item @b{Library_Kind}:
1521 @cindex @code{Library_Kind}
1522 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1523 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1524 which kind of library should be build (the default is to build a
1525 static library, that is an archive of object files that can potentially
1526 be linked into a static executable). When the library is set to be dynamic,
1527 a separate image is created that will be loaded independnently, usually
1528 at the start of the main program execution. Support for dynamic libraries is
1529 very platform specific, for instance on Windows it takes the form of a DLL
1530 while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1531 @file{.so}. Library project files, on the other hand, can be written in
1532 a platform independant way so that the same project file can be used to build
1533 a library on different Oses.
1535 If you need to build both a static and a dynamic library, it is recommended
1536 use two different object directories, since in some cases some extra code
1537 needs to be generated for the latter. For such cases, one can
1538 either define two different project files, or a single one which uses scenarios
1539 to indicate at the various kinds of library to be build and their
1540 corresponding object_dir.
1542 @cindex @code{Library_ALI_Dir}
1543 @item @b{Library_ALI_Dir}:
1544 This attribute may be specified to indicate the directory where the ALI
1545 files of the library are installed. By default, they are copied into the
1546 @code{Library_Dir} directory, but as for the executables where we have a
1547 separate @code{Exec_Dir} attribute, you might want to put them in a separate
1548 directory since there can be hundreds of them. The same restrictions as for
1549 the @code{Library_Dir} attribute apply.
1551 @cindex @code{Library_Version}
1552 @item @b{Library_Version}:
1553 This attribute is platform dependent, and has no effect on VMS and Windows.
1554 On Unix, it is used only for dynamic libraries as the internal
1555 name of the library (the @code{"soname"}). If the library file name (built
1556 from the @code{Library_Name}) is different from the @code{Library_Version},
1557 then the library file will be a symbolic link to the actual file whose name
1558 will be @code{Library_Version}. This follows the usual installation schemes
1559 for dynamic libraries on many Unix systems.
1561 @smallexample @c projectfile
1565 for Library_Dir use "lib";
1566 for Library_Name use "logging";
1567 for Library_Kind use "dynamic";
1568 for Library_Version use "liblogging.so." & Version;
1574 After the compilation, the directory @file{lib} will contain both a
1575 @file{libdummy.so.1} library and a symbolic link to it called
1578 @cindex @code{Library_GCC}
1579 @item @b{Library_GCC}:
1580 This attribute is the name of the tool to use instead of "gcc" to link shared
1581 libraries. A common use of this attribute is to define a wrapper script that
1582 accomplishes specific actions before calling gcc (which itself is calling the
1583 linker to build the library image).
1585 @cindex @code{Linker_Options}
1586 @item @b{Linker.Linker_Options}:
1587 This attribute specifies additional switches to be given to the linker when
1588 linking an executable. It is ignored when defined in the main project and
1589 taken into account in all other projects that are imported directly or
1590 indirectly. These switches complement the @code{Linker.Switches}
1591 defined in the main project. This is useful when a particular subsystem
1592 depends on an external library: adding this dependency as a
1593 @code{Linker_Options} in the project of the subsystem is more convenient than
1594 adding it to all the @code{Linker.Switches} of the main projects that depend
1595 upon this subsystem.
1599 @c ---------------------------------------------
1600 @node Using Library Projects
1601 @subsection Using Library Projects
1602 @c ---------------------------------------------
1605 When the builder detects that a project file is a library project file, it
1606 recompiles all sources of the project that need recompilation and rebuild the
1607 library if any of the sources have been recompiled. It then groups all object
1608 files into a single file, which is a shared or a static library. This library
1609 can later on be linked with multiple executables. Note that the use
1610 of shard libraries reduces the size of the final executable and can also reduce
1611 the memory footprint at execution time when the library is shared among several
1614 It is also possible to build @b{multi-language libraries}. When using
1615 @command{gprbuild} as a builder, multi-language library projects allow naturally
1616 the creation of multi-language libraries . @command{gnatmake}, does n ot try to
1617 compile non Ada sources. However, when the project is multi-language, it will
1618 automatically link all object files found in the object directory, whether or
1619 not they were compiled from an Ada source file. This specific behavior does not
1620 apply to Ada-only projects which only take into account the objects
1621 corresponding to the sources of the project.
1623 A non-library project can import a library project. When the builder is invoked
1624 on the former, the library of the latter is only rebuilt when absolutely
1625 necessary. For instance, if a unit of the
1626 library is not up-to-date but non of the executables need this unit, then the
1627 unit is not recompiled and the library is not reassembled.
1628 For instance, let's assume in our example that logging has the following
1629 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1630 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1631 @file{liblogging} will be rebuilt when compiling all the sources of
1632 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1633 include a @code{"with Log1"}.
1635 To ensure that all the sources in the @code{Logging} library are
1636 up to date, and that all the sources of @code{Build} are also up to date,
1637 the following two commands needs to be used:
1640 gnatmake -Plogging.gpr
1641 gnatmake -Pbuild.gpr
1645 All @file{ALI} files will also be copied from the object directory to the
1646 library directory. To build executables, @command{gnatmake} will use the
1647 library rather than the individual object files.
1650 Library projects can also be useful to describe a library that need to be used
1651 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1652 of the library sources are not available. Such library projects need simply to
1653 use the @code{Externally_Built} attribute as in the example below:
1655 @smallexample @c projectfile
1656 library project Extern_Lib is
1657 for Languages use ("Ada", "C");
1658 for Source_Dirs use ("lib_src");
1659 for Library_Dir use "lib2";
1660 for Library_Kind use "dynamic";
1661 for Library_Name use "l2";
1662 for Externally_Built use "true"; -- <<<<
1667 In the case of externally built libraries, the @code{Object_Dir}
1668 attribute does not need to be specified because it will never be
1671 The main effect of using such an externally built library project is mostly to
1672 affect the linker command in order to reference the desired library. It can
1673 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1674 in the project corresponding to the subsystem needing this external library.
1675 This latter method is more straightforward in simple cases but when several
1676 subsystems depend upon the same external library, finding the proper place
1677 for the @code{Linker.Linker_Options} might not be easy and if it is
1678 not placed properly, the final link command is likely to present ordering issues.
1679 In such a situation, it is better to use the externally built library project
1680 so that all other subsystems depending on it can declare this dependency thanks
1681 to a project @code{with} clause, which in turn will trigger the builder to find
1682 the proper order of libraries in the final link command.
1685 @c ---------------------------------------------
1686 @node Stand-alone Library Projects
1687 @subsection Stand-alone Library Projects
1688 @c ---------------------------------------------
1691 @cindex standalone libraries
1692 A @b{stand-alone library} is a library that contains the necessary code to
1693 elaborate the Ada units that are included in the library. A stand-alone
1694 library is a convenient way to add an Ada subsystem to a more global system
1695 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1696 transparent. However, stand-alone libraries are also useful when the main is in
1697 Ada: they provide a means for minimizing relinking & redeployement of complex
1698 systems when localized changes are made.
1700 The most proeminent characteristic of a stand-alone library is that it offers a
1701 distinction between interface units and implementation units. Only the former
1702 are visible to units outside the library. A stand-alone library project is thus
1703 characterised by a third attribute, @b{Library_Interface}, in addition to the
1704 two attributes that make a project a Library Project (@code{Library_Name} and
1705 @code{Library_Dir}).
1708 @item @b{Library_Interface}:
1709 @cindex @code{Library_Interface}
1710 This attribute defines an explicit subset of the units of the project.
1711 Projects importing this library project may only "with" units whose sources
1712 are listed in the @code{Library_Interface}. Other sources are considered
1713 implementation units.
1715 @smallexample @c projectfile
1717 for Library_Dir use "lib";
1718 for Library_Name use "loggin";
1719 for Library_Interface use ("lib1", "lib2"); -- unit names
1725 In order to include the elaboration code in the stand-alone library, the binder
1726 is invoked on the closure of the library units creating a package whose name
1727 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1728 This binder-generated package includes @b{initialization} and @b{finalization}
1729 procedures whose names depend on the library name (@code{logginginit} and
1730 @code{loggingfinal} in the example). The object corresponding to this package is
1731 included in the library.
1734 @item @b{Library_Auto_Init}:
1735 @cindex @code{Library_Auto_Init}
1736 A dynamic stand-alone Library is automatically initialized
1737 if automatic initialization of Stand-alone Libraries is supported on the
1738 platform and if attribute @b{Library_Auto_Init} is not specified or
1739 is specified with the value "true". A static Stand-alone Library is never
1740 automatically initialized. Specifying "false" for this attribute
1741 prevent automatic initialization.
1743 When a non-automatically initialized stand-alone library is used in an
1744 executable, its initialization procedure must be called before any service of
1745 the library is used. When the main subprogram is in Ada, it may mean that the
1746 initialization procedure has to be called during elaboration of another
1749 @item @b{Library_Dir}:
1750 @cindex @code{Library_Dir}
1751 For a stand-alone library, only the @file{ALI} files of the interface units
1752 (those that are listed in attribute @code{Library_Interface}) are copied to
1753 the library directory. As a consequence, only the interface units may be
1754 imported from Ada units outside of the library. If other units are imported,
1755 the binding phase will fail.
1757 @item @b{Binder.Default_Switches}:
1758 When a stand-alone library is bound, the switches that are specified in
1759 the attribute @b{Binder.Default_Switches ("Ada")} are
1760 used in the call to @command{gnatbind}.
1762 @item @b{Library_Options}:
1763 @cindex @code{Library_Options}
1764 This attribute may be used to specified additional switches to @command{gcc}
1765 when linking the library.
1767 @item @b{Library_Src_Dir}:
1768 @cindex @code{Library_Src_Dir}
1769 This attribute defines the location (absolute or relative to the project
1770 directory) where the sources of the interface units are copied at
1772 These sources includes the specs of the interface units along with the closure
1773 of sources necessary to compile them successfully. That may include bodies and
1774 subunits, when pragmas @code{Inline} are used, or when there is a generic
1775 units in the spec. This directory cannot point to the object directory or
1776 one of the source directories, but it can point to the library directory,
1777 which is the default value for this attribute.
1779 @item @b{Library_Symbol_Policy}:
1780 @cindex @code{Library_Symbol_Policy}
1781 This attribute controls the export of symbols and, on some platforms (like
1782 VMS) that have the notions of major and minor IDs built in the library
1783 files, it controls the setting of these IDs. It is not supported on all
1784 platforms (where it will just have no effect). It may have one of the
1788 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1789 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1790 is not defined, then it is equivalent to policy "autonomous". If there
1791 are exported symbols in the reference symbol file that are not in the
1792 object files of the interfaces, the major ID of the library is increased.
1793 If there are symbols in the object files of the interfaces that are not
1794 in the reference symbol file, these symbols are put at the end of the list
1795 in the newly created symbol file and the minor ID is increased.
1796 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1797 defined. The library will fail to build if the exported symbols in the
1798 object files of the interfaces do not match exactly the symbol in the
1800 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1801 The library will fail to build if there are symbols in the symbol file that
1802 are not in the exported symbols of the object files of the interfaces.
1803 Additional symbols in the object files are not added to the symbol file.
1804 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1805 must designate an existing file in the object directory. This symbol file
1806 is passed directly to the underlying linker without any symbol processing.
1810 @item @b{Library_Reference_Symbol_File}
1811 @cindex @code{Library_Reference_Symbol_File}
1812 This attribute may define the path name of a reference symbol file that is
1813 read when the symbol policy is either "compliant" or "controlled", on
1814 platforms that support symbol control, such as VMS, when building a
1815 stand-alone library. The path may be an absolute path or a path relative
1816 to the project directory.
1818 @item @b{Library_Symbol_File}
1819 @cindex @code{Library_Symbol_File}
1820 This attribute may define the name of the symbol file to be created when
1821 building a stand-alone library when the symbol policy is either "compliant",
1822 "controlled" or "restricted", on platforms that support symbol control,
1823 such as VMS. When symbol policy is "direct", then a file with this name
1824 must exist in the object directory.
1828 @c ---------------------------------------------
1829 @node Installing a library with project files
1830 @subsection Installing a library with project files
1831 @c ---------------------------------------------
1834 When using project files, library installation is part of the library build
1835 process. Thus no further action is needed in order to make use of the
1836 libraries that are built as part of the general application build. A usable
1837 version of the library is installed in the directory specified by the
1838 @code{Library_Dir} attribute of the library project file.
1840 You may want to install a library in a context different from where the library
1841 is built. This situation arises with third party suppliers, who may want
1842 to distribute a library in binary form where the user is not expected to be
1843 able to recompile the library. The simplest option in this case is to provide
1844 a project file slightly different from the one used to build the library, by
1845 using the @code{externally_built} attribute. @ref{Using Library Projects}
1847 @c ---------------------------------------------
1848 @node Project Extension
1849 @section Project Extension
1850 @c ---------------------------------------------
1853 During development of a large system, it is sometimes necessary to use
1854 modified versions of some of the source files, without changing the original
1855 sources. This can be achieved through the @b{project extension} facility.
1857 Suppose for instance that our example @code{Build} project is build every night
1858 for the whole team, in some shared directory. A developer usually need to work
1859 on a small part of the system, and might not want to have a copy of all the
1860 sources and all the object files (mostly because that would require too much
1861 disk space, time to recompile everything). He prefers to be able to override
1862 some of the source files in his directory, while taking advantage of all the
1863 object files generated at night.
1865 Another example can be taken from large software systems, where it is common to have
1866 multiple implementations of a common interface; in Ada terms, multiple
1867 versions of a package body for the same spec. For example, one implementation
1868 might be safe for use in tasking programs, while another might only be used
1869 in sequential applications. This can be modeled in GNAT using the concept
1870 of @emph{project extension}. If one project (the ``child'') @emph{extends}
1871 another project (the ``parent'') then by default all source files of the
1872 parent project are inherited by the child, but the child project can
1873 override any of the parent's source files with new versions, and can also
1874 add new files or remove unnecessary ones.
1875 This facility is the project analog of a type extension in
1876 object-oriented programming. Project hierarchies are permitted (an extending
1877 project may itself be extended), and a project that
1878 extends a project can also import other projects.
1880 A third example is that of using project extensions to provide different
1881 versions of the same system. For instance, assume that a @code{Common}
1882 project is used by two development branches. One of the branches has now
1883 been frozen, and no further change can be done to it or to @code{Common}.
1884 However, the other development branch still needs evolution of @code{Common}.
1885 Project extensions provide a flexible solution to create a new version
1886 of a subsystem while sharing and reusing as much as possible from the original
1889 A project extension inherits implicitly all the sources and objects from the
1890 project it extends. It is possible to create a new version of some of the
1891 sources in one of the additional source dirs of the extending project. Those new
1892 versions hide the original versions. Adding new sources or removing existing
1893 ones is also possible. Here is an example on how to extend the project
1894 @code{Build} from previous examples:
1896 @smallexample @c projectfile
1897 project Work extends "../bld/build.gpr" is
1902 The project after @b{extends} is the one being extended. As usual, it can be
1903 specified using an absolute path, or a path relative to any of the directories
1904 in the project path (@pxref{Project Dependencies}). This project does not
1905 specify source or object directories, so the default value for these attribute
1906 will be used that is to say the current directory (where project @code{Work} is
1907 placed). We can already compile that project with
1914 If no sources have been placed in the current directory, this command
1915 won't do anything, since this project does not change the
1916 sources it inherited from @code{Build}, therefore all the object files
1917 in @code{Build} and its dependencies are still valid and are reused
1920 Suppose we now want to supply an alternate version of @file{pack.adb}
1921 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
1922 We can create the new file Work's current directory (likely
1923 by copying the one from the @code{Build} project and making changes to
1924 it. If new packages are needed at the same time, we simply create
1925 new files in the source directory of the extending project.
1927 When we recompile, @command{gnatmake} will now automatically recompile
1928 this file (thus creating @file{pack.o} in the current directory) and
1929 any file that depends on it (thus creating @file{proc.o}). Finally, the
1930 executable is also linked locally.
1932 Note that we could have obtained the desired behavior using project import
1933 rather than project inheritance. A @code{base} project would contain the
1934 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
1935 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
1936 cannot contain the original version of @file{pack.adb} otherwise there would be
1937 2 versions of the same unit in the closure of the project and this is not
1938 allowed. Generally speaking, it is not recommended to put the spec and the
1939 body of a unit in different projects since this affects their autonomy and
1942 In a project file that extends another project, it is possible to
1943 indicate that an inherited source is @b{not part} of the sources of the
1944 extending project. This is necessary sometimes when a package spec has
1945 been overridden and no longer requires a body: in this case, it is
1946 necessary to indicate that the inherited body is not part of the sources
1947 of the project, otherwise there will be a compilation error
1948 when compiling the spec.
1950 @cindex @code{Excluded_Source_Files}
1951 @cindex @code{Excluded_Source_List_File}
1952 For that purpose, the attribute @b{Excluded_Source_Files} is used.
1953 Its value is a list of file names.
1954 It is also possible to use attribute @code{Excluded_Source_List_File}.
1955 Its value is the path of a text file containing one file name per
1958 @smallexample @c @projectfile
1959 project Work extends "../bld/build.gpr" is
1960 for Source_Files use ("pack.ads");
1961 -- New spec of Pkg does not need a completion
1962 for Excluded_Source_Files use ("pack.adb");
1967 An extending project retains all the switches specified in the
1971 * Project Hierarchy Extension::
1974 @c ---------------------------------------------
1975 @node Project Hierarchy Extension
1976 @subsection Project Hierarchy Extension
1977 @c ---------------------------------------------
1980 One of the fundamental restrictions in project extension is the following:
1981 @b{A project is not allowed to import directly or indirectly at the same time an
1982 extending project and one of its ancestors}.
1984 By means of example, consider the following hierarchy of projects.
1987 a.gpr contains package A1
1988 b.gpr, imports a.gpr and contains B1, which depends on A1
1989 c.gpr, imports b.gpr and contains C1, which depends on B1
1993 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
1994 create several extending projects:
1997 a_ext.gpr which extends a.gpr, and overrides A1
1998 b_ext.gpr which extends b.gpr and imports a_ext.gpr
1999 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2003 @smallexample @c projectfile
2004 project A_Ext extends "a.gpr" is
2005 for Source_Files use ("a1.adb", "a1.ads");
2009 project B_Ext extends "b.gpr" is
2013 project C_Ext extends "c.gpr" is
2014 for Source_Files use ("c1.adb");
2019 The extension @file{b_ext.gpr} is required, even though we are not overriding
2020 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2021 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2024 When extending a large system spanning multiple projects, it is often
2025 inconvenient to extend every project in the hierarchy that is impacted by a
2026 small change introduced in a low layer. In such cases, it is possible to create
2027 an @b{implicit extension} of entire hierarchy using @b{extends all}
2030 When the project is extended using @code{extends all} inheritance, all projects
2031 that are imported by it, both directly and indirectly, are considered virtually
2032 extended. That is, the project manager creates implicit projects
2033 that extend every project in the hierarchy; all these implicit projects do not
2034 control sources on their own and use the object directory of
2035 the "extending all" project.
2037 It is possible to explicitly extend one or more projects in the hierarchy
2038 in order to modify the sources. These extending projects must be imported by
2039 the "extending all" project, which will replace the corresponding virtual
2040 projects with the explicit ones.
2042 When building such a project hierarchy extension, the project manager will
2043 ensure that both modified sources and sources in implicit extending projects
2044 that depend on them, are recompiled.
2046 Thus, in our example we could create the following projects instead:
2049 a_ext.gpr, extends a.gpr and overrides A1
2050 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2055 @smallexample @c projectfile
2056 project A_Ext extends "a.gpr" is
2057 for Source_Files use ("a1.adb", "a1.ads");
2061 project C_Ext extends all "c.gpr" is
2062 for Source_Files use ("c1.adb");
2067 When building project @file{c_ext.gpr}, the entire modified project space is
2068 considered for recompilation, including the sources of @file{b.gpr} that are
2069 impacted by the changes in @code{A1} and @code{C1}.
2071 @c ---------------------------------------------
2072 @node Project File Reference
2073 @section Project File Reference
2074 @c ---------------------------------------------
2077 This section describes the syntactic structure of project files, the various
2078 constructs that can be used. Finally, it ends with a summary of all available
2082 * Project Declaration::
2083 * Qualified Projects::
2088 * Typed String Declaration::
2094 @c ---------------------------------------------
2095 @node Project Declaration
2096 @subsection Project Declaration
2097 @c ---------------------------------------------
2100 Project files have an Ada-like syntax. The minimal project file is:
2102 @smallexample @c projectfile
2110 The identifier @code{Empty} is the name of the project.
2111 This project name must be present after the reserved
2112 word @code{end} at the end of the project file, followed by a semi-colon.
2114 @b{Identifiers} (ie the user-defined names such as project or variable names)
2115 have the same syntax as Ada identifiers: they must start with a letter,
2116 and be followed by zero or more letters, digits or underscore characters;
2117 it is also illegal to have two underscores next to each other. Identifiers
2118 are always case-insensitive ("Name" is the same as "name").
2121 simple_name ::= identifier
2122 name ::= simple_name @{ . simple_name @}
2126 @b{Strings} are used for values of attributes or as indexes for these
2127 attributes. They are in general case sensitive, except when noted
2128 otherwise (in particular, strings representing file names will be case
2129 insensitive on some systems, so that "file.adb" and "File.adb" both
2130 represent the same file).
2132 @b{Reserved words} are the same as for standard Ada 95, and cannot
2133 be used for identifiers. In particular, the following words are currently
2134 used in project files, but others could be added later on. In bold are the
2135 extra reserved words in project files: @code{all, at, case, end, for, is,
2136 limited, null, others, package, renames, type, use, when, with, @b{extends},
2137 @b{external}, @b{project}}.
2139 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2140 hyphens through the end of the line.
2142 A project may be an @b{independent project}, entirely defined by a single
2143 project file. Any source file in an independent project depends only
2144 on the predefined library and other source files in the same project.
2145 But a project may also depend on other projects, either by importing them
2146 through @b{with clauses}, or by @b{extending} at most one other project. Both
2147 types of dependency can be used in the same project.
2149 A path name denotes a project file. It can be absolute or relative.
2150 An absolute path name includes a sequence of directories, in the syntax of
2151 the host operating system, that identifies uniquely the project file in the
2152 file system. A relative path name identifies the project file, relative
2153 to the directory that contains the current project, or relative to a
2154 directory listed in the environment variables ADA_PROJECT_PATH and
2155 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2156 operating system are case sensitive. As a special case, the directory
2157 separator can always be "/" even on Windows systems, so that project files
2158 can be made portable across architectures.
2159 The syntax of the environment variable ADA_PROJECT_PATH and
2160 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2161 semicolons on Windows.
2163 A given project name can appear only once in a context clause.
2165 It is illegal for a project imported by a context clause to refer, directly
2166 or indirectly, to the project in which this context clause appears (the
2167 dependency graph cannot contain cycles), except when one of the with clause
2168 in the cycle is a @b{limited with}.
2169 @c ??? Need more details here
2171 @smallexample @c projectfile
2172 with "other_project.gpr";
2173 project My_Project extends "extended.gpr" is
2178 These dependencies form a @b{directed graph}, potentially cyclic when using
2179 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
2182 A project's @b{immediate sources} are the source files directly defined by
2183 that project, either implicitly by residing in the project source directories,
2184 or explicitly through any of the source-related attributes.
2185 More generally, a project sources are the immediate sources of the project
2186 together with the immediate sources (unless overridden) of any
2187 project on which it depends directly or indirectly.
2189 A @b{project hierarchy} can be created, where projects are children of
2190 other projects. The name of such a child project must be @code{Parent.Child},
2191 where @code{Parent} is the name of the parent project. In particular, this
2192 makes all @code{with} clauses of the parent project automatically visible
2193 in the child project.
2196 project ::= context_clause project_declaration
2198 context_clause ::= @{with_clause@}
2199 with_clause ::= @i{with} path_name @{ , path_name @} ;
2200 path_name ::= string_literal
2202 project_declaration ::= simple_project_declaration | project_extension
2203 simple_project_declaration ::=
2204 @i{project} @i{<project_>}name @i{is}
2205 @{declarative_item@}
2206 @i{end} <project_>simple_name;
2209 @c ---------------------------------------------
2210 @node Qualified Projects
2211 @subsection Qualified Projects
2212 @c ---------------------------------------------
2215 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
2216 is identifiers or reserved words, to qualify the project.
2217 The current list of qualifiers is:
2220 @item @b{abstract}: qualifies a project with no sources. Such a
2221 project must either have no declaration of attributes @code{Source_Dirs},
2222 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
2223 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
2224 as empty. If it extends another project, the project it extends must also be a
2225 qualified abstract project.
2226 @item @b{standard}: a standard project is a non library project with sources.
2227 This is the default (implicit) qualifier.
2228 @item @b{aggregate}: for future extension
2229 @item @b{aggregate library}: for future extension
2230 @item @b{library}: a library project must declare both attributes
2231 @code{Library_Name} and @code{Library_Dir}.
2232 @item @b{configuration}: a configuration project cannot be in a project tree.
2233 It describes compilers and other tools to @code{gprbuild}.
2237 @c ---------------------------------------------
2239 @subsection Declarations
2240 @c ---------------------------------------------
2243 Declarations introduce new entities that denote types, variables, attributes,
2244 and packages. Some declarations can only appear immediately within a project
2245 declaration. Others can appear within a project or within a package.
2248 declarative_item ::= simple_declarative_item
2249 | typed_string_declaration
2250 | package_declaration
2252 simple_declarative_item ::= variable_declaration
2253 | typed_variable_declaration
2254 | attribute_declaration
2258 empty_declaration ::= @i{null} ;
2262 An empty declaration is allowed anywhere a declaration is allowed. It has
2265 @c ---------------------------------------------
2267 @subsection Packages
2268 @c ---------------------------------------------
2271 A project file may contain @b{packages}, that group attributes (typically
2272 all the attributes that are used by one of the GNAT tools).
2274 A package with a given name may only appear once in a project file.
2275 The following packages are currently supported in project files
2276 (See @pxref{Attributes} for the list of attributes that each can contain).
2280 This package specifies characteristics useful when invoking the binder either
2281 directly via the @command{gnat} driver or when using a builder such as
2282 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
2284 This package specifies the compilation options used when building an
2285 executable or a library for a project. Most of the options should be
2286 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
2287 but there are some general options that should be defined in this
2288 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
2291 This package specifies the options used when calling the checking tool
2292 @command{gnatcheck} via the @command{gnat} driver. Its attribute
2293 @b{Default_Switches} has the same semantics as for the package
2294 @code{Builder}. The first string should always be @code{-rules} to specify
2295 that all the other options belong to the @code{-rules} section of the
2296 parameters to @command{gnatcheck}.
2298 This package specifies the compilation options used by the compiler for
2299 each languages. @xref{Tools Options in Project Files}.
2300 @item Cross_Reference
2301 This package specifies the options used when calling the library tool
2302 @command{gnatxref} via the @command{gnat} driver. Its attributes
2303 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2304 package @code{Builder}.
2306 This package specifies the options used when calling the tool
2307 @command{gnatelim} via the @command{gnat} driver. Its attributes
2308 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2309 package @code{Builder}.
2311 This package specifies the options used when calling the search tool
2312 @command{gnatfind} via the @command{gnat} driver. Its attributes
2313 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2314 package @code{Builder}.
2316 This package the options to use when invoking @command{gnatls} via the
2317 @command{gnat} driver.
2319 This package specifies the options used when calling the tool
2320 @command{gnatstub} via the @command{gnat} driver. Its attributes
2321 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2322 package @code{Builder}.
2324 This package specifies the options used when starting an integrated
2325 development environment, for instance @command{GPS} or @command{Gnatbench}.
2326 @xref{The Development Environments}.
2328 This package specifies the options used by the linker.
2329 @xref{Main Subprograms}.
2331 This package specifies the options used when calling the tool
2332 @command{gnatmetric} via the @command{gnat} driver. Its attributes
2333 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2334 package @code{Builder}.
2336 This package specifies the naming conventions that apply
2337 to the source files in a project. In particular, these conventions are
2338 used to automatically find all source files in the source directories,
2339 or given a file name to find out its language for proper processing.
2340 @xref{Naming Schemes}.
2341 @item Pretty_Printer
2342 This package specifies the options used when calling the formatting tool
2343 @command{gnatpp} via the @command{gnat} driver. Its attributes
2344 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2345 package @code{Builder}.
2347 This package specifies the options used when calling the tool
2348 @command{gnatstack} via the @command{gnat} driver. Its attributes
2349 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2350 package @code{Builder}.
2352 This package specifies the options used when calling the tool
2353 @command{gnatsync} via the @command{gnat} driver.
2357 In its simplest form, a package may be empty:
2359 @smallexample @c projectfile
2369 A package may contain @b{attribute declarations},
2370 @b{variable declarations} and @b{case constructions}, as will be
2373 When there is ambiguity between a project name and a package name,
2374 the name always designates the project. To avoid possible confusion, it is
2375 always a good idea to avoid naming a project with one of the
2376 names allowed for packages or any name that starts with @code{gnat}.
2378 A package can also be defined by a @b{renaming declaration}. The new package
2379 renames a package declared in a different project file, and has the same
2380 attributes as the package it renames. The name of the renamed package
2381 must be the same as the name of the renaming package. The project must
2382 contain a package declaration with this name, and the project
2383 must appear in the context clause of the current project, or be its parent
2384 project. It is not possible to add or override attributes to the renaming
2385 project. If you need to do so, you should declare a standard package, and
2386 assign the value of the attributes one by one (@code{for Switches ("Ada")
2387 use Other_Project.Compiler'Switches ("Ada")}).
2389 Packages that are renamed in other project files often come from project files
2390 that have no sources: they are just used as templates. Any modification in the
2391 template will be reflected automatically in all the project files that rename
2392 a package from the template. This is a very common way to share settings
2396 package_declaration ::= package_spec | package_renaming
2398 @i{package} @i{<package_>}simple_name @i{is}
2399 @{simple_declarative_item@}
2400 @i{end} package_identifier ;
2401 package_renaming ::==
2402 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
2405 @c ---------------------------------------------
2407 @subsection Expressions
2408 @c ---------------------------------------------
2411 An expression is any value that can be assigned to an attribute or a
2412 variable. It is either a litteral value, or a construct requiring runtime
2413 computation by the project manager. In a project file, the computed value of
2414 an expression is either a string or a list of strings.
2416 A string value is one of:
2418 @item A literal string, for instance @code{"comm/my_proj.gpr"}
2419 @item The name of a variable that evaluates to a string (@pxref{Variables})
2420 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
2421 @item An external reference (@pxref{External Values})
2422 @item A concatenation of the above, as in @code{"prefix_" & Var}.
2427 A list of strings is one of the following:
2430 @item A parenthesized comma-separated list of zero or more string expressions, for
2431 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
2432 @item The name of a variable that evaluates to a list of strings
2433 @item The name of an attribute that evaluates to a list of strings
2434 @item A concatenation of a list of strings and a string (as defined above), for
2435 instance @code{("A", "B") & "C"}
2436 @item A concatenation of two lists of strings
2441 The following is the grammar for expressions
2444 string_literal ::= "@{string_element@}" -- Same as Ada
2445 string_expression ::= string_literal
2448 | attribute_reference
2449 | ( string_expression @{ & string_expression @} )
2450 string_list ::= ( string_expression @{ , string_expression @} )
2451 | @i{string_variable}_name
2452 | @i{string_}attribute_reference
2453 term ::= string_expression | string_list
2454 expression ::= term @{ & term @} -- Concatenation
2458 Concatenation involves strings and list of strings. As soon as a list of
2459 strings is involved, the result of the concatenation is a list of strings. The
2460 following Ada declarations show the existing operators:
2462 @smallexample @c ada
2463 function "&" (X : String; Y : String) return String;
2464 function "&" (X : String_List; Y : String) return String_List;
2465 function "&" (X : String_List; Y : String_List) return String_List;
2469 Here are some specific examples:
2471 @smallexample @c projectfile
2473 List := () & File_Name; -- One string in this list
2474 List2 := List & (File_Name & ".orig"); -- Two strings
2475 Big_List := List & Lists2; -- Three strings
2476 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
2480 @c ---------------------------------------------
2481 @node External Values
2482 @subsection External Values
2483 @c ---------------------------------------------
2486 An external value is an expression whose value is obtained from the command
2487 that invoked the processing of the current project file (typically a
2488 gnatmake or gprbuild command).
2491 external_value ::= @i{external} ( string_literal [, string_literal] )
2495 The first string_literal is the string to be used on the command line or
2496 in the environment to specify the external value. The second string_literal,
2497 if present, is the default to use if there is no specification for this
2498 external value either on the command line or in the environment.
2500 Typically, the external value will either exist in the
2501 ^environment variables^logical name^
2502 or be specified on the command line through the
2503 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
2504 are specified, then the command line value is used, so that a user can more
2505 easily override the value.
2507 The function @code{external} always returns a string, possibly empty if the
2508 value was not found in the environment and no default was specified in the
2509 call to @code{external}.
2511 An external reference may be part of a string expression or of a string
2512 list expression, and can therefore appear in a variable declaration or
2513 an attribute declaration.
2515 Most of the time, this construct is used to initialize typed variables, which
2516 are then used in @b{case} statements to control the value assigned to
2517 attributes in various scenarios. Thus such variables are often called
2518 @b{scenario variables}.
2520 @c ---------------------------------------------
2521 @node Typed String Declaration
2522 @subsection Typed String Declaration
2523 @c ---------------------------------------------
2526 A @b{type declaration} introduces a discrete set of string literals.
2527 If a string variable is declared to have this type, its value
2528 is restricted to the given set of literals. These are the only named
2529 types in project files. A string type may only be declared at the project
2530 level, not inside a package.
2533 typed_string_declaration ::=
2534 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
2538 The string literals in the list are case sensitive and must all be different.
2539 They may include any graphic characters allowed in Ada, including spaces.
2540 Here is an example of a string type declaration:
2542 @smallexample @c projectfile
2543 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
2547 Variables of a string type are called @b{typed variables}; all other
2548 variables are called @b{untyped variables}. Typed variables are
2549 particularly useful in @code{case} constructions, to support conditional
2550 attribute declarations. (@pxref{Case Statements}).
2552 A string type may be referenced by its name if it has been declared in the same
2553 project file, or by an expanded name whose prefix is the name of the project
2554 in which it is declared.
2556 @c ---------------------------------------------
2558 @subsection Variables
2559 @c ---------------------------------------------
2562 @b{Variables} store values (strings or list of strings) and can appear
2563 as part of an expression. The declaration of a variable creates the
2564 variable and assigns the value of the expression to it. The name of the
2565 variable is available immediately after the assignment symbol, if you
2566 need to reuse its old value to compute the new value. Before the completion
2567 of its first declaration, the value of a variable defaults to the empty
2570 A @b{typed} variable can be used as part of a @b{case} expression to
2571 compute the value, but it can only be declared once in the project file,
2572 so that all case statements see the same value for the variable. This
2573 provides more consistency and makes the project easier to understand.
2574 The syntax for its declaration is identical to the Ada syntax for an
2575 object declaration. In effect, a typed variable acts as a constant.
2577 An @b{untyped} variable can be declared and overridden multiple times
2578 within the same project. It is declared implicitly through an Ada
2579 assignment. The first declaration establishes the kind of the variable
2580 (string or list of strings) and successive declarations must respect
2581 the initial kind. Assignments are executed in the order in which they
2582 appear, so the new value replaces the old one and any subsequent reference
2583 to the variable uses the new value.
2585 A variable may be declared at the project file level, or within a package.
2588 typed_variable_declaration ::=
2589 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
2590 variable_declaration ::= @i{<variable_>}simple_name := expression;
2594 Here are some examples of variable declarations:
2596 @smallexample @c projectfile
2598 This_OS : OS := external ("OS"); -- a typed variable declaration
2599 That_OS := "GNU/Linux"; -- an untyped variable declaration
2601 Name := "readme.txt";
2602 Save_Name := Name & ".saved";
2605 List_With_One_Element := ("-gnaty");
2606 List_With_Two_Elements := List_With_One_Element & "-gnatg";
2607 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
2612 A @b{variable reference} may take several forms:
2615 @item The simple variable name, for a variable in the current package (if any)
2616 or in the current project
2617 @item An expanded name, whose prefix is a context name.
2622 A @b{context} may be one of the following:
2625 @item The name of an existing package in the current project
2626 @item The name of an imported project of the current project
2627 @item The name of an ancestor project (i.e., a project extended by the current
2628 project, either directly or indirectly)
2629 @item An expanded name whose prefix is an imported/parent project name, and
2630 whose selector is a package name in that project.
2634 @c ---------------------------------------------
2636 @subsection Attributes
2637 @c ---------------------------------------------
2640 A project (and its packages) may have @b{attributes} that define
2641 the project's properties. Some attributes have values that are strings;
2642 others have values that are string lists.
2645 attribute_declaration ::=
2646 simple_attribute_declaration | indexed_attribute_declaration
2647 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
2648 indexed_attribute_declaration ::=
2649 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
2650 attribute_designator ::=
2651 @i{<simple_attribute_>}simple_name
2652 | @i{<indexed_attribute_>}simple_name ( string_literal )
2656 There are two categories of attributes: @b{simple attributes}
2657 and @b{indexed attributes}.
2658 Each simple attribute has a default value: the empty string (for string
2659 attributes) and the empty list (for string list attributes).
2660 An attribute declaration defines a new value for an attribute, and overrides
2661 the previous value. The syntax of a simple attribute declaration is similar to
2662 that of an attribute definition clause in Ada.
2664 Some attributes are indexed. These attributes are mappings whose
2665 domain is a set of strings. They are declared one association
2666 at a time, by specifying a point in the domain and the corresponding image
2668 Like untyped variables and simple attributes, indexed attributes
2669 may be declared several times. Each declaration supplies a new value for the
2670 attribute, and replaces the previous setting.
2672 Here are some examples of attribute declarations:
2674 @smallexample @c projectfile
2675 -- simple attributes
2676 for Object_Dir use "objects";
2677 for Source_Dirs use ("units", "test/drivers");
2679 -- indexed attributes
2680 for Body ("main") use "Main.ada";
2681 for Switches ("main.ada") use ("-v", "-gnatv");
2682 for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
2684 -- indexed attributes copy (from package Builder in project Default)
2685 -- The package name must always be specified, even if it is the current
2687 for Default_Switches use Default.Builder'Default_Switches;
2691 Attributes references may be appear anywhere in expressions, and are used
2692 to retrieve the value previously assigned to the attribute. If an attribute
2693 has not been set in a given package or project, its value defaults to the
2694 empty string or the empty list.
2697 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
2698 attribute_prefix ::= @i{project}
2699 | @i{<project_>}simple_name
2700 | package_identifier
2701 | @i{<project_>}simple_name . package_identifier
2707 @smallexample @c projectfile
2709 Naming'Dot_Replacement
2710 Imported_Project'Source_Dirs
2711 Imported_Project.Naming'Casing
2712 Builder'Default_Switches ("Ada")
2716 The prefix of an attribute may be:
2719 @item @code{project} for an attribute of the current project
2720 @item The name of an existing package of the current project
2721 @item The name of an imported project
2722 @item The name of a parent project that is extended by the current project
2723 @item An expanded name whose prefix is imported/parent project name,
2724 and whose selector is a package name
2729 Legal attribute names are listed below, including the package in
2730 which they must be declared. These names are case-insensitive. The
2731 semantics for the attributes is explained in great details in other sections.
2733 The column @emph{index} indicates whether the attribute is an indexed attribute,
2734 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
2735 system (file). The text is between brackets ([]) if the index is optional.
2737 @multitable @columnfractions .3 .1 .2 .4
2738 @headitem Attribute Name @tab Value @tab Package @tab Index
2739 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
2740 @item Name @tab string @tab - @tab (Read-only, name of project)
2741 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
2742 @item Source_Files @tab list @tab - @tab -
2743 @item Source_Dirs @tab list @tab - @tab -
2744 @item Source_List_File @tab string @tab - @tab -
2745 @item Locally_Removed_Files @tab list @tab - @tab -
2746 @item Excluded_Source_Files @tab list @tab - @tab -
2747 @item Object_Dir @tab string @tab - @tab -
2748 @item Exec_Dir @tab string @tab - @tab -
2749 @item Excluded_Source_Dirs @tab list @tab - @tab -
2750 @item Excluded_Source_Files @tab list @tab - @tab -
2751 @item Excluded_Source_List_File @tab list @tab - @tab -
2752 @item Inherit_Source_Path @tab list @tab - @tab insensitive
2753 @item Languages @tab list @tab - @tab -
2754 @item Main @tab list @tab - @tab -
2755 @item Main_Language @tab string @tab - @tab -
2756 @item Externally_Built @tab string @tab - @tab -
2757 @item Roots @tab list @tab - @tab file
2759 Library-related attributes @tab @tab @tab @pxref{Library Projects}
2760 @item Library_Dir @tab string @tab - @tab -
2761 @item Library_Name @tab string @tab - @tab -
2762 @item Library_Kind @tab string @tab - @tab -
2763 @item Library_Version @tab string @tab - @tab -
2764 @item Library_Interface @tab string @tab - @tab -
2765 @item Library_Auto_Init @tab string @tab - @tab -
2766 @item Library_Options @tab list @tab - @tab -
2767 @item Library_Src_Dir @tab string @tab - @tab -
2768 @item Library_ALI_Dir @tab string @tab - @tab -
2769 @item Library_GCC @tab string @tab - @tab -
2770 @item Library_Symbol_File @tab string @tab - @tab -
2771 @item Library_Symbol_Policy @tab string @tab - @tab -
2772 @item Library_Reference_Symbol_File @tab string @tab - @tab -
2773 @item Interfaces @tab list @tab - @tab -
2775 Naming @tab @tab @tab @pxref{Naming Schemes}
2776 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
2777 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
2778 @item Separate_Suffix @tab string @tab Naming @tab -
2779 @item Casing @tab string @tab Naming @tab -
2780 @item Dot_Replacement @tab string @tab Naming @tab -
2781 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
2782 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
2783 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
2784 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
2786 Building @tab @tab @tab @pxref{Switches and Project Files}
2787 @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)
2788 @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)
2789 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
2790 @item Local_Config_File @tab string @tab insensitive @tab -
2791 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
2792 @item Global_Compilation_Switches @tab list @tab Builder @tab language
2793 @item Executable @tab string @tab Builder @tab [file]
2794 @item Executable_Suffix @tab string @tab Builder @tab -
2795 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
2797 IDE (used and created by GPS) @tab @tab @tab
2798 @item Remote_Host @tab string @tab IDE @tab -
2799 @item Program_Host @tab string @tab IDE @tab -
2800 @item Communication_Protocol @tab string @tab IDE @tab -
2801 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
2802 @item Debugger_Command @tab string @tab IDE @tab -
2803 @item Gnatlist @tab string @tab IDE @tab -
2804 @item VCS_Kind @tab string @tab IDE @tab -
2805 @item VCS_File_Check @tab string @tab IDE @tab -
2806 @item VCS_Log_Check @tab string @tab IDE @tab -
2808 Configuration files @tab @tab @tab See gprbuild manual
2809 @item Default_Language @tab string @tab - @tab -
2810 @item Run_Path_Option @tab list @tab - @tab -
2811 @item Run_Path_Origin @tab string @tab - @tab -
2812 @item Separate_Run_Path_Options @tab string @tab - @tab -
2813 @item Toolchain_Version @tab string @tab - @tab insensitive
2814 @item Toolchain_Description @tab string @tab - @tab insensitive
2815 @item Object_Generated @tab string @tab - @tab insensitive
2816 @item Objects_Linked @tab string @tab - @tab insensitive
2817 @item Target @tab string @tab - @tab -
2818 @item Library_Builder @tab string @tab - @tab -
2819 @item Library_Support @tab string @tab - @tab -
2820 @item Archive_Builder @tab list @tab - @tab -
2821 @item Archive_Builder_Append_Option @tab list @tab - @tab -
2822 @item Archive_Indexer @tab list @tab - @tab -
2823 @item Archive_Suffix @tab string @tab - @tab -
2824 @item Library_Partial_Linker @tab list @tab - @tab -
2825 @item Shared_Library_Prefix @tab string @tab - @tab -
2826 @item Shared_Library_Suffix @tab string @tab - @tab -
2827 @item Symbolic_Link_Supported @tab string @tab - @tab -
2828 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
2829 @item Library_Auto_Init_Supported @tab string @tab - @tab -
2830 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
2831 @item Library_Version_Switches @tab list @tab - @tab -
2832 @item Library_Install_Name_Option @tab string @tab - @tab -
2833 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
2834 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
2835 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
2836 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
2837 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
2838 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
2839 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
2840 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
2841 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
2842 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
2843 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
2844 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitve (language)
2845 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
2846 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
2847 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
2848 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
2849 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
2850 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
2851 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
2852 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
2853 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
2854 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
2855 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
2856 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
2857 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
2858 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
2859 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
2860 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
2861 @item Prefix @tab string @tab Binder @tab insensitive (language)
2862 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
2863 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
2864 @item Linker_Options @tab list @tab Linker @tab -
2865 @item Map_File_Options @tab string @tab Linker @tab -
2866 @item Executable_Switches @tab list @tab Linker @tab -
2867 @item Lib_Dir_Switch @tab string @tab Linker @tab -
2868 @item Lib_Name_Switch @tab string @tab Linker @tab -
2869 @item Max_Command_Line_Length @tab string @tab Linker @tab -
2870 @item Response_File_Format @tab string @tab Linker @tab -
2871 @item Response_File_Switches @tab list @tab Linker @tab -
2874 @c ---------------------------------------------
2875 @node Case Statements
2876 @subsection Case Statements
2877 @c ---------------------------------------------
2880 A @b{case} statement is used in a project file to effect conditional
2881 behavior. Through this statement, you can set the value of attributes
2882 and variables depending on the value previously assigned to a typed
2885 All choices in a choice list must be distinct. Unlike Ada, the choice
2886 lists of all alternatives do not need to include all values of the type.
2887 An @code{others} choice must appear last in the list of alternatives.
2889 The syntax of a @code{case} construction is based on the Ada case statement
2890 (although the @code{null} statement for empty alternatives is optional).
2892 The case expression must be a typed string variable, whose value is often
2893 given by an external reference (@pxref{External Values}).
2895 Each alternative starts with the reserved word @code{when}, either a list of
2896 literal strings separated by the @code{"|"} character or the reserved word
2897 @code{others}, and the @code{"=>"} token.
2898 Each literal string must belong to the string type that is the type of the
2900 After each @code{=>}, there are zero or more statements. The only
2901 statements allowed in a case construction are other case statements,
2902 attribute declarations and variable declarations. String type declarations and
2903 package declarations are not allowed. Variable declarations are restricted to
2904 variables that have already been declared before the case construction.
2908 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
2911 @i{when} discrete_choice_list =>
2913 | attribute_declaration
2914 | variable_declaration
2915 | empty_declaration@}
2917 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
2921 Here is a typical example:
2923 @smallexample @c projectfile
2926 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
2927 OS : OS_Type := external ("OS", "GNU/Linux");
2931 when "GNU/Linux" | "Unix" =>
2932 for Switches ("Ada") use ("-gnath");
2934 for Switches ("Ada") use ("-gnatP");
2943 @c ---------------------------------------------
2944 @node Tools Supporting Project Files
2945 @chapter Tools Supporting Project Files
2946 @c ---------------------------------------------
2952 * gnatmake and Project Files::
2953 * The GNAT Driver and Project Files::
2954 * The Development Environments::
2955 * Cleaning up with GPRclean::
2958 @c ---------------------------------------------
2959 @node gnatmake and Project Files
2960 @section gnatmake and Project Files
2961 @c ---------------------------------------------
2964 This section covers several topics related to @command{gnatmake} and
2965 project files: defining ^switches^switches^ for @command{gnatmake}
2966 and for the tools that it invokes; specifying configuration pragmas;
2967 the use of the @code{Main} attribute; building and rebuilding library project
2971 * Switches Related to Project Files::
2972 * Switches and Project Files::
2973 * Specifying Configuration Pragmas::
2974 * Project Files and Main Subprograms::
2975 * Library Project Files::
2978 @c ---------------------------------------------
2979 @node Switches Related to Project Files
2980 @subsection Switches Related to Project Files
2981 @c ---------------------------------------------
2984 The following switches are used by GNAT tools that support project files:
2988 @item ^-P^/PROJECT_FILE=^@var{project}
2989 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
2990 Indicates the name of a project file. This project file will be parsed with
2991 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
2992 if any, and using the external references indicated
2993 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
2995 There may zero, one or more spaces between @option{-P} and @var{project}.
2998 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3000 Since the Project Manager parses the project file only after all the switches
3001 on the command line are checked, the order of the switches
3002 @option{^-P^/PROJECT_FILE^},
3003 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3004 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3006 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3007 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3008 Indicates that external variable @var{name} has the value @var{value}.
3009 The Project Manager will use this value for occurrences of
3010 @code{external(name)} when parsing the project file.
3013 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3021 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3022 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3023 @var{name}, only the last one is used.
3025 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3026 takes precedence over the value of the same name in the environment.
3028 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3029 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3030 Indicates the verbosity of the parsing of GNAT project files.
3033 @option{-vP0} means Default;
3034 @option{-vP1} means Medium;
3035 @option{-vP2} means High.
3039 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3043 The default is ^Default^DEFAULT^: no output for syntactically correct
3045 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3046 only the last one is used.
3048 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3049 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3050 Add directory <dir> at the beginning of the project search path, in order,
3051 after the current working directory.
3055 @cindex @option{-eL} (any project-aware tool)
3056 Follow all symbolic links when processing project files.
3059 @item ^--subdirs^/SUBDIRS^=<subdir>
3060 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3061 This switch is recognized by gnatmake and gnatclean. It indicate that the real
3062 directories (except the source directories) are the subdirectories <subdir>
3063 of the directories specified in the project files. This applies in particular
3064 to object directories, library directories and exec directories. If the
3065 subdirectories do not exist, they are created automatically.
3069 @c ---------------------------------------------
3070 @node Switches and Project Files
3071 @subsection Switches and Project Files
3072 @c ---------------------------------------------
3076 It is not currently possible to specify VMS style qualifiers in the project
3077 files; only Unix style ^switches^switches^ may be specified.
3080 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3081 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3082 attribute, a @code{Switches} attribute, or both;
3083 as their names imply, these ^switch^switch^-related
3084 attributes affect the ^switches^switches^ that are used for each of these GNAT
3086 @command{gnatmake} is invoked. As will be explained below, these
3087 component-specific ^switches^switches^ precede
3088 the ^switches^switches^ provided on the @command{gnatmake} command line.
3090 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3091 indexed by language name (case insensitive) whose value is a string list.
3094 @smallexample @c projectfile
3097 for ^Default_Switches^Default_Switches^ ("Ada")
3098 use ("^-gnaty^-gnaty^",
3105 The @code{Switches} attribute is indexed on a file name (which may or may
3106 not be case sensitive, depending
3107 on the operating system) whose value is a string list. For example:
3109 @smallexample @c projectfile
3112 for Switches ("main1.adb")
3114 for Switches ("main2.adb")
3121 For the @code{Builder} package, the file names must designate source files
3122 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
3123 file names must designate @file{ALI} or source files for main subprograms.
3124 In each case just the file name without an explicit extension is acceptable.
3126 For each tool used in a program build (@command{gnatmake}, the compiler, the
3127 binder, and the linker), the corresponding package @dfn{contributes} a set of
3128 ^switches^switches^ for each file on which the tool is invoked, based on the
3129 ^switch^switch^-related attributes defined in the package.
3130 In particular, the ^switches^switches^
3131 that each of these packages contributes for a given file @var{f} comprise:
3134 @item the value of attribute @code{Switches (@var{f})},
3135 if it is specified in the package for the given file,
3136 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
3137 if it is specified in the package.
3142 If neither of these attributes is defined in the package, then the package does
3143 not contribute any ^switches^switches^ for the given file.
3145 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
3146 two sets, in the following order: those contributed for the file
3147 by the @code{Builder} package;
3148 and the switches passed on the command line.
3150 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
3151 the ^switches^switches^ passed to the tool comprise three sets,
3152 in the following order:
3156 the applicable ^switches^switches^ contributed for the file
3157 by the @code{Builder} package in the project file supplied on the command line;
3160 those contributed for the file by the package (in the relevant project file --
3161 see below) corresponding to the tool; and
3164 the applicable switches passed on the command line.
3167 The term @emph{applicable ^switches^switches^} reflects the fact that
3168 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
3169 tools, depending on the individual ^switch^switch^.
3171 @command{gnatmake} may invoke the compiler on source files from different
3172 projects. The Project Manager will use the appropriate project file to
3173 determine the @code{Compiler} package for each source file being compiled.
3174 Likewise for the @code{Binder} and @code{Linker} packages.
3176 As an example, consider the following package in a project file:
3178 @smallexample @c projectfile
3182 for ^Default_Switches^Default_Switches^ ("Ada")
3184 for Switches ("a.adb")
3186 for Switches ("b.adb")
3195 If @command{gnatmake} is invoked with this project file, and it needs to
3196 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
3197 @file{a.adb} will be compiled with the ^switch^switch^
3199 @file{b.adb} with ^switches^switches^
3201 and @option{^-gnaty^-gnaty^},
3202 and @file{c.adb} with @option{^-g^-g^}.
3204 The following example illustrates the ordering of the ^switches^switches^
3205 contributed by different packages:
3207 @smallexample @c projectfile
3211 for Switches ("main.adb")
3220 for Switches ("main.adb")
3228 If you issue the command:
3231 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
3235 then the compiler will be invoked on @file{main.adb} with the following
3236 sequence of ^switches^switches^
3239 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
3243 with the last @option{^-O^-O^}
3244 ^switch^switch^ having precedence over the earlier ones;
3245 several other ^switches^switches^
3246 (such as @option{^-c^-c^}) are added implicitly.
3248 The ^switches^switches^
3250 and @option{^-O1^-O1^} are contributed by package
3251 @code{Builder}, @option{^-O2^-O2^} is contributed
3252 by the package @code{Compiler}
3253 and @option{^-O0^-O0^} comes from the command line.
3255 The @option{^-g^-g^}
3256 ^switch^switch^ will also be passed in the invocation of
3259 A final example illustrates switch contributions from packages in different
3262 @smallexample @c projectfile
3265 for Source_Files use ("pack.ads", "pack.adb");
3267 for ^Default_Switches^Default_Switches^ ("Ada")
3268 use ("^-gnata^-gnata^");
3276 for Source_Files use ("foo_main.adb", "bar_main.adb");
3278 for Switches ("foo_main.adb")
3288 procedure Foo_Main is
3297 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
3301 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
3302 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
3303 @option{^-gnato^-gnato^} (passed on the command line).
3304 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
3305 are @option{^-g^-g^} from @code{Proj4.Builder},
3306 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
3307 and @option{^-gnato^-gnato^} from the command line.
3309 When using @command{gnatmake} with project files, some ^switches^switches^ or
3310 arguments may be expressed as relative paths. As the working directory where
3311 compilation occurs may change, these relative paths are converted to absolute
3312 paths. For the ^switches^switches^ found in a project file, the relative paths
3313 are relative to the project file directory, for the switches on the command
3314 line, they are relative to the directory where @command{gnatmake} is invoked.
3315 The ^switches^switches^ for which this occurs are:
3321 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
3323 ^-o^-o^, object files specified in package @code{Linker} or after
3324 -largs on the command line). The exception to this rule is the ^switch^switch^
3325 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
3327 @c ---------------------------------------------
3328 @node Specifying Configuration Pragmas
3329 @subsection Specifying Configuration Pragmas
3330 @c ---------------------------------------------
3333 When using @command{gnatmake} with project files, if there exists a file
3334 @file{gnat.adc} that contains configuration pragmas, this file will be
3337 Configuration pragmas can be defined by means of the following attributes in
3338 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
3339 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
3341 Both these attributes are single string attributes. Their values is the path
3342 name of a file containing configuration pragmas. If a path name is relative,
3343 then it is relative to the project directory of the project file where the
3344 attribute is defined.
3346 When compiling a source, the configuration pragmas used are, in order,
3347 those listed in the file designated by attribute
3348 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
3349 project file, if it is specified, and those listed in the file designated by
3350 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
3351 the project file of the source, if it exists.
3353 @c ---------------------------------------------
3354 @node Project Files and Main Subprograms
3355 @subsection Project Files and Main Subprograms
3356 @c ---------------------------------------------
3359 When using a project file, you can invoke @command{gnatmake}
3360 with one or several main subprograms, by specifying their source files on the
3364 gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
3368 Each of these needs to be a source file of the same project, except
3369 when the switch ^-u^/UNIQUE^ is used.
3371 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
3372 same project, one of the project in the tree rooted at the project specified
3373 on the command line. The package @code{Builder} of this common project, the
3374 "main project" is the one that is considered by @command{gnatmake}.
3376 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
3377 imported directly or indirectly by the project specified on the command line.
3378 Note that if such a source file is not part of the project specified on the
3379 command line, the ^switches^switches^ found in package @code{Builder} of the
3380 project specified on the command line, if any, that are transmitted
3381 to the compiler will still be used, not those found in the project file of
3384 When using a project file, you can also invoke @command{gnatmake} without
3385 explicitly specifying any main, and the effect depends on whether you have
3386 defined the @code{Main} attribute. This attribute has a string list value,
3387 where each element in the list is the name of a source file (the file
3388 extension is optional) that contains a unit that can be a main subprogram.
3390 If the @code{Main} attribute is defined in a project file as a non-empty
3391 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
3392 line, then invoking @command{gnatmake} with this project file but without any
3393 main on the command line is equivalent to invoking @command{gnatmake} with all
3394 the file names in the @code{Main} attribute on the command line.
3397 @smallexample @c projectfile
3400 for Main use ("main1", "main2", "main3");
3406 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
3408 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
3410 When the project attribute @code{Main} is not specified, or is specified
3411 as an empty string list, or when the switch @option{-u} is used on the command
3412 line, then invoking @command{gnatmake} with no main on the command line will
3413 result in all immediate sources of the project file being checked, and
3414 potentially recompiled. Depending on the presence of the switch @option{-u},
3415 sources from other project files on which the immediate sources of the main
3416 project file depend are also checked and potentially recompiled. In other
3417 words, the @option{-u} switch is applied to all of the immediate sources of the
3420 When no main is specified on the command line and attribute @code{Main} exists
3421 and includes several mains, or when several mains are specified on the
3422 command line, the default ^switches^switches^ in package @code{Builder} will
3423 be used for all mains, even if there are specific ^switches^switches^
3424 specified for one or several mains.
3426 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
3427 the specific ^switches^switches^ for each main, if they are specified.
3429 @c ---------------------------------------------
3430 @node Library Project Files
3431 @subsection Library Project Files
3432 @c ---------------------------------------------
3435 When @command{gnatmake} is invoked with a main project file that is a library
3436 project file, it is not allowed to specify one or more mains on the command
3439 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
3440 ^-l^/ACTION=LINK^ have special meanings.
3443 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
3444 to @command{gnatmake} that @command{gnatbind} should be invoked for the
3447 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
3448 to @command{gnatmake} that the binder generated file should be compiled
3449 (in the case of a stand-alone library) and that the library should be built.
3453 @c ---------------------------------------------
3454 @node The GNAT Driver and Project Files
3455 @section The GNAT Driver and Project Files
3456 @c ---------------------------------------------
3459 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
3460 can benefit from project files:
3461 (@command{^gnatbind^gnatbind^},
3462 @command{^gnatcheck^gnatcheck^},
3463 @command{^gnatclean^gnatclean^},
3464 @command{^gnatelim^gnatelim^},
3465 @command{^gnatfind^gnatfind^},
3466 @command{^gnatlink^gnatlink^},
3467 @command{^gnatls^gnatls^},
3468 @command{^gnatmetric^gnatmetric^},
3469 @command{^gnatpp^gnatpp^},
3470 @command{^gnatstub^gnatstub^},
3471 and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
3472 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
3473 They must be invoked through the @command{gnat} driver.
3475 The @command{gnat} driver is a wrapper that accepts a number of commands and
3476 calls the corresponding tool. It was designed initially for VMS platforms (to
3477 convert VMS qualifiers to Unix-style switches), but it is now available on all
3480 On non-VMS platforms, the @command{gnat} driver accepts the following commands
3484 @item BIND to invoke @command{^gnatbind^gnatbind^}
3485 @item CHOP to invoke @command{^gnatchop^gnatchop^}
3486 @item CLEAN to invoke @command{^gnatclean^gnatclean^}
3487 @item COMP or COMPILE to invoke the compiler
3488 @item ELIM to invoke @command{^gnatelim^gnatelim^}
3489 @item FIND to invoke @command{^gnatfind^gnatfind^}
3490 @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
3491 @item LINK to invoke @command{^gnatlink^gnatlink^}
3492 @item LS or LIST to invoke @command{^gnatls^gnatls^}
3493 @item MAKE to invoke @command{^gnatmake^gnatmake^}
3494 @item NAME to invoke @command{^gnatname^gnatname^}
3495 @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
3496 @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
3497 @item METRIC to invoke @command{^gnatmetric^gnatmetric^}
3498 @item STUB to invoke @command{^gnatstub^gnatstub^}
3499 @item XREF to invoke @command{^gnatxref^gnatxref^}
3504 (note that the compiler is invoked using the command
3505 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
3507 On non-VMS platforms, between @command{gnat} and the command, two
3508 special switches may be used:
3511 @item @command{-v} to display the invocation of the tool.
3512 @item @command{-dn} to prevent the @command{gnat} driver from removing
3513 the temporary files it has created. These temporary files are
3514 configuration files and temporary file list files.
3519 The command may be followed by switches and arguments for the invoked
3523 gnat bind -C main.ali
3529 Switches may also be put in text files, one switch per line, and the text
3530 files may be specified with their path name preceded by '@@'.
3533 gnat bind @@args.txt main.ali
3537 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
3538 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
3539 (@option{^-P^/PROJECT_FILE^},
3540 @option{^-X^/EXTERNAL_REFERENCE^} and
3541 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
3542 the switches of the invoking tool.
3544 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
3545 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
3546 the immediate sources of the specified project file.
3548 When GNAT METRIC is used with a project file, but with no source
3549 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
3550 with all the immediate sources of the specified project file and with
3551 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
3554 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
3555 a project file, no source is specified on the command line and
3556 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
3557 the underlying tool (^gnatpp^gnatpp^ or
3558 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
3559 not only for the immediate sources of the main project.
3561 (-U stands for Universal or Union of the project files of the project tree)
3564 For each of the following commands, there is optionally a corresponding
3565 package in the main project.
3568 @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
3570 @item package @code{Check} for command CHECK (invoking
3571 @code{^gnatcheck^gnatcheck^})
3573 @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
3575 @item package @code{Cross_Reference} for command XREF (invoking
3576 @code{^gnatxref^gnatxref^})
3578 @item package @code{Eliminate} for command ELIM (invoking
3579 @code{^gnatelim^gnatelim^})
3581 @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
3583 @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
3585 @item package @code{Gnatstub} for command STUB
3586 (invoking @code{^gnatstub^gnatstub^})
3588 @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
3590 @item package @code{Check} for command CHECK
3591 (invoking @code{^gnatcheck^gnatcheck^})
3593 @item package @code{Metrics} for command METRIC
3594 (invoking @code{^gnatmetric^gnatmetric^})
3596 @item package @code{Pretty_Printer} for command PP or PRETTY
3597 (invoking @code{^gnatpp^gnatpp^})
3602 Package @code{Gnatls} has a unique attribute @code{Switches},
3603 a simple variable with a string list value. It contains ^switches^switches^
3604 for the invocation of @code{^gnatls^gnatls^}.
3606 @smallexample @c projectfile
3619 All other packages have two attribute @code{Switches} and
3620 @code{^Default_Switches^Default_Switches^}.
3622 @code{Switches} is an indexed attribute, indexed by the
3623 source file name, that has a string list value: the ^switches^switches^ to be
3624 used when the tool corresponding to the package is invoked for the specific
3627 @code{^Default_Switches^Default_Switches^} is an attribute,
3628 indexed by the programming language that has a string list value.
3629 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
3630 ^switches^switches^ for the invocation of the tool corresponding
3631 to the package, except if a specific @code{Switches} attribute
3632 is specified for the source file.
3634 @smallexample @c projectfile
3638 for Source_Dirs use ("./**");
3649 for ^Default_Switches^Default_Switches^ ("Ada")
3650 use ("^-gnatv^-gnatv^",
3651 "^-gnatwa^-gnatwa^");
3657 for ^Default_Switches^Default_Switches^ ("Ada")
3665 for ^Default_Switches^Default_Switches^ ("Ada")
3667 for Switches ("main.adb")
3676 for ^Default_Switches^Default_Switches^ ("Ada")
3683 package Cross_Reference is
3684 for ^Default_Switches^Default_Switches^ ("Ada")
3689 end Cross_Reference;
3695 With the above project file, commands such as
3698 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
3699 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
3700 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
3701 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
3702 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
3706 will set up the environment properly and invoke the tool with the switches
3707 found in the package corresponding to the tool:
3708 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
3709 except @code{Switches ("main.adb")}
3710 for @code{^gnatlink^gnatlink^}.
3711 It is also possible to invoke some of the tools,
3712 (@code{^gnatcheck^gnatcheck^},
3713 @code{^gnatmetric^gnatmetric^},
3714 and @code{^gnatpp^gnatpp^})
3715 on a set of project units thanks to the combination of the switches
3716 @option{-P}, @option{-U} and possibly the main unit when one is interested
3717 in its closure. For instance,
3723 will compute the metrics for all the immediate units of project
3726 gnat metric -Pproj -U
3730 will compute the metrics for all the units of the closure of projects
3731 rooted at @code{proj}.
3733 gnat metric -Pproj -U main_unit
3737 will compute the metrics for the closure of units rooted at
3738 @code{main_unit}. This last possibility relies implicitly
3739 on @command{gnatbind}'s option @option{-R}. But if the argument files for the
3740 tool invoked by the the @command{gnat} driver are explicitly specified
3741 either directly or through the tool @option{-files} option, then the tool
3742 is called only for these explicitly specified files.
3744 @c ---------------------------------------------
3745 @node The Development Environments
3746 @section The Development Environments
3747 @c ---------------------------------------------
3750 See the appropriate manuals for more details. These environments will
3751 store a number of settings in the project itself, when they are meant
3752 to be shared by the whole team working on the project. Here are the
3753 attributes defined in the package @b{IDE} in projects.
3757 This is a simple attribute. Its value is a string that designates the remote
3758 host in a cross-compilation environment, to be used for remote compilation and
3759 debugging. This field should not be specified when running on the local
3763 This is a simple attribute. Its value is a string that specifies the
3764 name of IP address of the embedded target in a cross-compilation environment,
3765 on which the program should execute.
3767 @item Communication_Protocol
3768 This is a simple string attribute. Its value is the name of the protocol
3769 to use to communicate with the target in a cross-compilation environment,
3770 e.g.@: @code{"wtx"} or @code{"vxworks"}.
3772 @item Compiler_Command
3773 This is an associative array attribute, whose domain is a language name. Its
3774 value is string that denotes the command to be used to invoke the compiler.
3775 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
3776 gnatmake, in particular in the handling of switches.
3778 @item Debugger_Command
3779 This is simple attribute, Its value is a string that specifies the name of
3780 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
3782 @item Default_Switches
3783 This is an associative array attribute. Its indexes are the name of the
3784 external tools that the GNAT Programming System (GPS) is supporting. Its
3785 value is a list of switches to use when invoking that tool.
3788 This is a simple attribute. Its value is a string that specifies the name
3789 of the @command{gnatls} utility to be used to retrieve information about the
3790 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
3792 This is a simple attribute. Its value is a string used to specify the
3793 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
3794 ClearCase or Perforce.
3796 @item VCS_File_Check
3797 This is a simple attribute. Its value is a string that specifies the
3798 command used by the VCS to check the validity of a file, either
3799 when the user explicitly asks for a check, or as a sanity check before
3803 This is a simple attribute. Its value is a string that specifies
3804 the command used by the VCS to check the validity of a log file.
3806 @item VCS_Repository_Root
3807 The VCS repository root path. This is used to create tags or branches
3808 of the repository. For subversion the value should be the @code{URL}
3809 as specified to check-out the working copy of the repository.
3811 @item VCS_Patch_Root
3812 The local root directory to use for building patch file. All patch chunks
3813 will be relative to this path. The root project directory is used if
3814 this value is not defined.
3818 @c ---------------------------------------------
3819 @node Cleaning up with GPRclean
3820 @section Cleaning up with GPRclean
3821 @c ---------------------------------------------
3824 The GPRclean tool removes the files created by GPRbuild.
3825 At a minimum, to invoke GPRclean you must specify a main project file
3826 in a command such as @code{gprclean proj.gpr} or @code{gprclean -P proj.gpr}.
3828 Examples of invocation of GPRclean:
3831 gprclean -r prj1.gpr
3832 gprclean -c -P prj2.gpr
3836 * Switches for GPRclean::
3839 @c ---------------------------------------------
3840 @node Switches for GPRclean
3841 @subsection Switches for GPRclean
3842 @c ---------------------------------------------
3845 The switches for GPRclean are:
3848 @item @option{--config=<main config project file name>} : Specify the
3849 configuration project file name
3851 @item @option{--autoconf=<config project file name>}
3853 This specifies a configuration project file name that already exists or will
3854 be created automatically. Option @option{--autoconf=}
3855 cannot be specified more than once. If the configuration project file
3856 specified with @option{--autoconf=} exists, then it is used. Otherwise,
3857 @value{gprconfig} is invoked to create it automatically.
3859 @item @option{-c} : Only delete compiler-generated files. Do not delete
3860 executables and libraries.
3862 @item @option{-f} : Force deletions of unwritable files
3864 @item @option{-F} : Display full project path name in brief error messages
3866 @item @option{-h} : Display this message
3868 @item @option{-n} : Do not delete files, only list files to delete
3870 @item @option{-P<proj>} : Use Project File @emph{<proj>}.
3872 @item @option{-q} : Be quiet/terse. There is no output, except to report
3875 @item @option{-r} : (recursive) Clean all projects referenced by the main
3876 project directly or indirectly. Without this switch, GPRclean only
3877 cleans the main project.
3879 @item @option{-v} : Verbose mode
3881 @item @option{-vPx} : Specify verbosity when parsing Project Files.
3882 x = 0 (default), 1 or 2.
3884 @item @option{-Xnm=val} : Specify an external reference for Project Files.