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} may take a pattern as an index, such as in:
639 @b{package} Compiler @b{is}
640 @b{for} Default_Switches ("Ada") @b{use} ("-O2");
641 @b{for} Switches ("pkg*") @b{use} ("-O0");
646 Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0,
650 @code{Switches} can also be given a language name as index instead of a file
651 name in which case it has the same semantics as @emph{Default_Switches}.
652 However, indexes with wild cards are never valid for language name.
654 @item @b{Local_Configuration_Pragmas}:
655 @cindex @code{Local_Configuration_Pragmas}
656 this attribute may specify the path
657 of a file containing configuration pragmas for use by the Ada compiler,
658 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
659 used for all the sources of the project.
663 The switches for the other tools are defined in a similar manner through the
664 @b{Default_Switches} and @b{Switches} attributes, respectively in the
665 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
666 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
667 package (for linking executables).
669 @c ---------------------------------------------
670 @node Compiling with Project Files
671 @subsection Compiling with Project Files
672 @c ---------------------------------------------
675 Now that our project files are written, let's build our executable.
676 Here is the command we would use from the command line:
679 gnatmake ^-Pbuild^/PROJECT_FILE=build^
683 This will automatically build the executables specified through the
684 @emph{Main} attribute: for each, it will compile or recompile the
685 sources for which the object file does not exist or is not up-to-date; it
686 will then run the binder; and finally run the linker to create the
689 @command{gnatmake} only knows how to handle Ada files. By using
690 @command{gprbuild} as a builder, you could automatically manage C files the
691 same way: create the file @file{utils.c} in the @file{common} directory,
692 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
695 gprbuild ^-Pbuild^/PROJECT_FILE=build^
699 Gprbuild knows how to recompile the C files and will
700 recompile them only if one of their dependencies has changed. No direct
701 indication on how to build the various elements is given in the
702 project file, which describes the project properties rather than a
703 set of actions to be executed. Here is the invocation of
704 @command{gprbuild} when building a multi-language program:
717 Notice the three steps described earlier:
720 @item The first three gcc commands correspond to the compilation phase.
721 @item The gprbind command corresponds to the post-compilation phase.
722 @item The last gcc command corresponds to the final link.
727 @cindex @option{-v} option (for GPRbuild)
728 The default output of GPRbuild's execution is kept reasonably simple and easy
729 to understand. In particular, some of the less frequently used commands are not
730 shown, and some parameters are abbreviated. So it is not possible to rerun the
731 effect ofthe gprbuild command by cut-and-pasting its output. GPRbuild's option
732 @code{-v} provides a much more verbose output which includes, among other
733 information, more complete compilation, post-compilation and link commands.
735 @c ---------------------------------------------
736 @node Executable File Names
737 @subsection Executable File Names
738 @c ---------------------------------------------
741 @cindex @code{Executable}
742 By default, the executable name corresponding to a main file is
743 computed from the main source file name. Through the attribute
744 @b{Builder.Executable}, it is possible to change this default.
746 For instance, instead of building @command{proc} (or @command{proc.exe}
747 on Windows), we could configure our project file to build "proc1"
748 (resp proc1.exe) with the following addition:
750 @smallexample @c projectfile
752 ... -- same as before
754 for Executable ("proc.adb") use "proc1";
760 @cindex @code{Executable_Suffix}
761 Attribute @b{Executable_Suffix}, when specified, may change the suffix
762 of the executable files, when no attribute @code{Executable} applies:
763 its value replace the platform-specific executable suffix.
764 The default executable suffix is empty on UNIX and ".exe" on Windows.
766 It is also possible to change the name of the produced executable by using the
767 command line switch @option{-o}. When several mains are defined in the project,
768 it is not possible to use the @option{-o} switch and the only way to change the
769 names of the executable is provided by Attributes @code{Executable} and
770 @code{Executable_Suffix}.
772 @c ---------------------------------------------
773 @node Avoid Duplication With Variables
774 @subsection Avoid Duplication With Variables
775 @c ---------------------------------------------
778 To illustrate some other project capabilities, here is a slightly more complex
779 project using similar sources and a main program in C:
781 @smallexample @c projectfile
783 for Languages use ("Ada", "C");
784 for Source_Dirs use ("common");
785 for Object_Dir use "obj";
786 for Main use ("main.c");
788 C_Switches := ("-pedantic");
789 for Default_Switches ("C") use C_Switches;
790 for Default_Switches ("Ada") use ("-gnaty");
791 for Switches ("main.c") use C_Switches & ("-g");
797 This project has many similarities with the previous one.
798 As expected, its @code{Main} attribute now refers to a C source.
799 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
800 executable will be put in the directory @file{obj}.
802 The most noticeable difference is the use of a variable in the
803 @emph{Compiler} package to store settings used in several attributes.
804 This avoids text duplication, and eases maintenance (a single place to
805 modify if we want to add new switches for C files). We will revisit
806 the use of variables in the context of scenarios (@pxref{Scenarios in
809 In this example, we see how the file @file{main.c} can be compiled with
810 the switches used for all the other C files, plus @option{-g}.
811 In this specific situation the use of a variable could have been
812 replaced by a reference to the @code{Default_Switches} attribute:
814 @smallexample @c projectfile
815 for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
819 Note the tick (@emph{'}) used to refer to attributes defined in a package.
821 Here is the output of the GPRbuild command using this project:
825 gcc -c -pedantic -g main.c
826 gcc -c -gnaty proc.adb
827 gcc -c -gnaty pack.adb
828 gcc -c -pedantic utils.c
835 The default switches for Ada sources,
836 the default switches for C sources (in the compilation of @file{lib.c}),
837 and the specific switches for @file{main.c} have all been taken into
840 @c ---------------------------------------------
842 @subsection Naming Schemes
843 @c ---------------------------------------------
846 Sometimes an Ada software system is ported from one compilation environment to
847 another (say GNAT), and the file are not named using the default GNAT
848 conventions. Instead of changing all the file names, which for a variety of
849 reasons might not be possible, you can define the relevant file naming scheme
850 in the @b{Naming} package of your project file.
852 The naming scheme has two distinct goals for the project manager: it
853 allows finding of source files when searching in the source
854 directories, and given a source file name it makes it possible to guess
855 the associated language, and thus the compiler to use.
857 Note that the use by the Ada compiler of pragmas Source_File_Name is not
858 supported when using project files. You must use the features described in this
859 paragraph. You can however specify other configuration pragmas
860 (@pxref{Specifying Configuration Pragmas}).
862 The following attributes can be defined in package @code{Naming}:
866 @cindex @code{Casing}
867 Its value must be one of @code{"lowercase"} (the default if
868 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
869 casing of file names with regards to the Ada unit name. Given an Ada unit
870 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
871 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
872 On Windows, file names are case insensitive, so this attribute is
875 @item @b{Dot_Replacement}:
876 @cindex @code{Dot_Replacement}
877 This attribute specifies the string that should replace the "." in unit
878 names. Its default value is @code{"-"} so that a unit
879 @code{Parent.Child} is expected to be found in the file
880 @file{parent-child.adb}. The replacement string must satisfy the following
881 requirements to avoid ambiguities in the naming scheme:
884 @item It must not be empty
885 @item It cannot start or end with an alphanumeric character
886 @item It cannot be a single underscore
887 @item It cannot start with an underscore followed by an alphanumeric
888 @item It cannot contain a dot @code{'.'} except if the entire string
893 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
894 @cindex @code{Spec_Suffix}
895 @cindex @code{Specification_Suffix}
896 For Ada, these attributes give the suffix used in file names that contain
897 specifications. For other languages, they give the extension for files
898 that contain declaration (header files in C for instance). The attribute
899 is indexed on the language.
900 The two attributes are equivalent, but the latter is obsolescent.
901 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
902 @code{"^.ads^.ADS^"}.
903 The value must satisfy the following requirements:
906 @item It must not be empty
907 @item It cannot start with an alphanumeric character
908 @item It cannot start with an underscore followed by an alphanumeric character
909 @item It must include at least one dot
913 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
914 @cindex @code{Body_Suffix}
915 @cindex @code{Implementation_Suffix}
916 These attributes give the extension used for file names that contain
917 code (bodies in Ada). They are indexed on the language. The second
918 version is obsolescent and fully replaced by the first attribute.
920 These attributes must satisfy the same requirements as @code{Spec_Suffix}.
921 In addition, they must be different from any of the values in
923 If @code{Body_Suffix ("Ada")} is not specified, then the default is
924 @code{"^.adb^.ADB^"}.
926 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
927 same string, then a file name that ends with the longest of these two
928 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
929 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
931 If the suffix does not start with a '.', a file with a name exactly equal
932 to the suffix will also be part of the project (for instance if you define
933 the suffix as @code{Makefile}, a file called @file{Makefile} will be part
934 of the project. This capability is usually not interesting when building.
935 However, it might become useful when a project is also used to
936 find the list of source files in an editor, like the GNAT Programming System
939 @item @b{Separate_Suffix}:
940 @cindex @code{Separate_Suffix}
941 This attribute is specific to Ada. It denotes the suffix used in file names
942 that contain separate bodies. If it is not specified, then it defaults to
943 same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the
944 @code{Body_Suffix} attribute. The only accepted index is "Ada".
946 @item @b{Spec} or @b{Specification}:
948 @cindex @code{Specification}
949 This attribute @code{Spec} can be used to define the source file name for a
950 given Ada compilation unit's spec. The index is the literal name of the Ada
951 unit (case insensitive). The value is the literal base name of the file that
952 contains this unit's spec (case sensitive or insensitive depending on the
953 operating system). This attribute allows the definition of exceptions to the
954 general naming scheme, in case some files do not follow the usual
957 When a source file contains several units, the relative position of the unit
958 can be indicated. The first unit in the file is at position 1
960 @smallexample @c projectfile
961 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
962 for Spec ("top") use "foo.a" at 1;
963 for Spec ("foo") use "foo.a" at 2;
966 @item @b{Body} or @b{Implementation}:
968 @cindex @code{Implementation}
969 These attribute play the same role as @emph{Spec} for Ada bodies.
971 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
972 @cindex @code{Specification_Exceptions}
973 @cindex @code{Implementation_Exceptions}
974 These attributes define exceptions to the naming scheme for languages
975 other than Ada. They are indexed on the language name, and contain
976 a list of file names respectively for headers and source code.
982 For example, the following package models the Apex file naming rules:
984 @smallexample @c projectfile
987 for Casing use "lowercase";
988 for Dot_Replacement use ".";
989 for Spec_Suffix ("Ada") use ".1.ada";
990 for Body_Suffix ("Ada") use ".2.ada";
997 For example, the following package models the DEC Ada file naming rules:
999 @smallexample @c projectfile
1002 for Casing use "lowercase";
1003 for Dot_Replacement use "__";
1004 for Spec_Suffix ("Ada") use "_.ada";
1005 for Body_Suffix ("Ada") use ".ada";
1011 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1012 names in lower case)
1015 @c ---------------------------------------------
1016 @node Organizing Projects into Subsystems
1017 @section Organizing Projects into Subsystems
1018 @c ---------------------------------------------
1021 A @b{subsystem} is a coherent part of the complete system to be built. It is
1022 represented by a set of sources and one single object directory. A system can
1023 be composed of a single subsystem when it is simple as we have seen in the
1024 first section. Complex systems are usually composed of several interdependent
1025 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1026 other one is required to build it, and in particular if visibility on some of
1027 the sources of this other subsystem is required. Each subsystem is usually
1028 represented by its own project file.
1030 In this section, the previous example is being extended. Let's assume some
1031 sources of our @code{Build} project depend on other sources.
1032 For instance, when building a graphical interface, it is usual to depend upon
1033 a graphical library toolkit such as GtkAda. Furthermore, we also need
1034 sources from a logging module we had previously written.
1037 * Project Dependencies::
1038 * Cyclic Project Dependencies::
1039 * Sharing Between Projects::
1040 * Global Attributes::
1043 @c ---------------------------------------------
1044 @node Project Dependencies
1045 @subsection Project Dependencies
1046 @c ---------------------------------------------
1049 GtkAda comes with its own project file (appropriately called
1050 @file{gtkada.gpr}), and we will assume we have already built a project
1051 called @file{logging.gpr} for the logging module. With the information provided
1052 so far in @file{build.gpr}, building the application would fail with an error
1053 indicating that the gtkada and logging units that are relied upon by the sources
1054 of this project cannot be found.
1056 This is easily solved by adding the following @b{with} clauses at the beginning
1059 @smallexample @c projectfile
1061 with "a/b/logging.gpr";
1068 @cindex @code{Externally_Built}
1069 When such a project is compiled, @command{gnatmake} will automatically
1070 check the other projects and recompile their sources when needed. It will also
1071 recompile the sources from @code{Build} when needed, and finally create the
1072 executable. In some cases, the implementation units needed to recompile a
1073 project are not available, or come from some third-party and you do not want to
1074 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1075 "true" can be set, indicating to the builder that this project can be assumed
1076 to be up-to-date, and should not be considered for recompilation. In Ada, if
1077 the sources of this externally built project were compiled with another version
1078 of the compiler or with incompatible options, the binder will issue an error.
1080 The project's @code{with} clause has several effects. It provides source
1081 visibility between projects during the compilation process. It also guarantees
1082 that the necessary object files from @code{Logging} and @code{GtkAda} are
1083 available when linking @code{Build}.
1085 As can be seen in this example, the syntax for importing projects is similar
1086 to the syntax for importing compilation units in Ada. However, project files
1087 use literal strings instead of names, and the @code{with} clause identifies
1088 project files rather than packages.
1090 Each literal string after @code{with} is the path
1091 (absolute or relative) to a project file. The @code{.gpr} extension is
1092 optional, although we recommend adding it. If no extension is specified,
1093 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1094 the file is searched for exactly as written in the @code{with} clause,
1095 that is with no extension.
1097 @cindex project path
1098 When a relative path or a base name is used, the
1099 project files are searched relative to each of the directories in the
1100 @b{project path}. This path includes all the directories found with the
1101 following algorithm, in that order, as soon as a matching file is found,
1105 @item First, the file is searched relative to the directory that contains the
1106 current project file.
1108 @cindex @code{ADA_PROJECT_PATH}
1109 @cindex @code{GPR_PROJECT_PATH}
1110 Then it is searched relative to all the directories specified in the
1111 ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and
1112 @b{ADA_PROJECT_PATH} (in that order) if they exist. The former is
1113 recommended, the latter is kept for backward compatibility.
1114 @item Finally, it is searched relative to the default project directories.
1115 Such directories depends on the tool used. For @command{gnatmake}, there is
1116 one default project directory: @file{<prefix>/lib/gnat/}. In our example,
1117 @file{gtkada.gpr} is found in the predefined directory if it was installed at
1118 the same root as GNAT.
1123 Some tools also support extending the project path from the command line,
1124 generally through the @option{-aP}. You can see the value of the project
1125 path by using the @command{gnatls -v} command.
1127 Any symbolic link will be fully resolved in the directory of the
1128 importing project file before the imported project file is examined.
1130 Any source file in the imported project can be used by the sources of the
1131 importing project, transitively.
1132 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1133 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1134 import @code{C} explicitly. However, this is not recommended, because if
1135 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1136 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1137 that will report such indirect dependencies.
1139 One very important aspect of a project hierarchy is that
1140 @b{a given source can only belong to one project} (otherwise the project manager
1141 would not know which settings apply to it and when to recompile it). It means
1142 that different project files do not usually share source directories or
1143 when they do, they need to specify precisely which project owns which sources
1144 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1145 can each own a source with the same base file name as long as they live in
1146 different directories. The latter is not true for Ada Sources because of the
1147 correlation betwen source files and Ada units.
1149 @c ---------------------------------------------
1150 @node Cyclic Project Dependencies
1151 @subsection Cyclic Project Dependencies
1152 @c ---------------------------------------------
1155 Cyclic dependencies are mostly forbidden:
1156 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1157 is not allowed to import @code{A}. However, there are cases when cyclic
1158 dependencies would be beneficial. For these cases, another form of import
1159 between projects exists: the @b{limited with}. A project @code{A} that
1160 imports a project @code{B} with a straight @code{with} may also be imported,
1161 directly or indirectly, by @code{B} through a @code{limited with}.
1163 The difference between straight @code{with} and @code{limited with} is that
1164 the name of a project imported with a @code{limited with} cannot be used in the
1165 project importing it. In particular, its packages cannot be renamed and
1166 its variables cannot be referred to.
1168 @smallexample @c 0projectfile
1172 For Exec_Dir use B'Exec_Dir; -- ok
1175 limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
1177 For Exec_Dir use A'Exec_Dir; -- not ok
1184 limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
1186 For Exec_Dir use A'Exec_Dir; -- not ok
1190 @c ---------------------------------------------
1191 @node Sharing Between Projects
1192 @subsection Sharing Between Projects
1193 @c ---------------------------------------------
1196 When building an application, it is common to have similar needs in severa of
1197 the projects corresponding to the subsystems under construction. For instance,
1198 they will all have the same compilation switches.
1200 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1201 switches for all sources of a subsystem is simple: it is just a matter of
1202 adding a @code{Compiler.Default_Switches} attribute to each project files with
1203 the same value. Of course, that means duplication of data, and both places need
1204 to be changed in order to recompile the whole application with different
1205 switches. It can become a real problem if there are many subsystems and thus
1206 many project files to edit.
1208 There are two main approaches to avoiding this duplication:
1211 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1212 to reference the attribute in Logging, either through a package renaming,
1213 or by referencing the attribute. The following example shows both cases:
1215 @smallexample @c projectfile
1218 for Switches ("Ada") use ("-O2");
1221 for Switches ("Ada") use ("-E");
1227 package Compiler renames Logging.Compiler;
1229 for Switches ("Ada") use Logging.Binder'Switches ("Ada");
1235 The solution used for @code{Compiler} gets the same value for all
1236 attributes of the package, but you cannot modify anything from the
1237 package (adding extra switches or some exceptions). The second
1238 version is more flexible, but more verbose.
1240 If you need to refer to the value of a variable in an imported
1241 project, rather than an attribute, the syntax is similar but uses
1242 a "." rather than an apostrophe. For instance:
1244 @smallexample @c projectfile
1247 Var1 := Imported.Var;
1251 @item The second approach is to define the switches in a third project.
1252 That project is setup without any sources (so that, as opposed to
1253 the first example, none of the project plays a special role), and
1254 will only be used to define the attributes. Such a project is
1255 typically called @file{shared.gpr}.
1257 @smallexample @c projectfile
1258 abstract project Shared is
1259 for Source_Files use (); -- no project
1261 for Switches ("Ada") use ("-O2");
1267 package Compiler renames Shared.Compiler;
1272 package Compiler renames Shared.Compiler;
1277 As for the first example, we could have chosen to set the attributes
1278 one by one rather than to rename a package. The reason we explicitly
1279 indicate that @code{Shared} has no sources is so that it can be created
1280 in any directory and we are sure it shares no sources with @code{Build}
1281 or @code{Logging}, which of course would be invalid.
1283 @cindex project qualifier
1284 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1285 This qualifier is optional, but helps convey the message that we do not
1286 intend this project to have sources (@pxref{Qualified Projects} for
1291 @c ---------------------------------------------
1292 @node Global Attributes
1293 @subsection Global Attributes
1294 @c ---------------------------------------------
1297 We have already seen many examples of attributes used to specify a special
1298 option of one of the tools involved in the build process. Most of those
1299 attributes are project specific. That it to say, they only affect the invocation
1300 of tools on the sources of the project where they are defined.
1302 There are a few additional attributes that apply to all projects in a
1303 hierarchy as long as they are defined on the "main" project.
1304 The main project is the project explicitly mentioned on the command-line.
1305 The project hierarchy is the "with"-closure of the main project.
1307 Here is a list of commonly used global attributes:
1310 @item @b{Builder.Global_Configuration_Pragmas}:
1311 @cindex @code{Global_Configuration_Pragmas}
1312 This attribute points to a file that contains configuration pragmas
1313 to use when building executables. These pragmas apply for all
1314 executables build from this project hierarchy. As we have seen before,
1315 additional pragmas can be specified on a per-project basis by setting the
1316 @code{Compiler.Local_Configuration_Pragmas} attribute.
1318 @item @b{Builder.Global_Compilation_Switches}:
1319 @cindex @code{Global_Compilation_Switches}
1320 This attribute is a list of compiler switches to use when compiling any
1321 source file in the project hierarchy. These switches are used in addition
1322 to the ones defined in the @code{Compiler} package, which only apply to
1323 the sources of the corresponding project. This attribute is indexed on
1324 the name of the language.
1328 Using such global capabilities is convenient. It can also lead to unexpected
1329 behavior. Especially when several subsystems are shared among different main
1330 projects and the different global attributes are not
1331 compatible. Note that using aggregate projects can be a safer and more powerful
1332 replacement to global attributes.
1334 @c ---------------------------------------------
1335 @node Scenarios in Projects
1336 @section Scenarios in Projects
1337 @c ---------------------------------------------
1340 Various aspects of the projects can be modified based on @b{scenarios}. These
1341 are user-defined modes that change the behavior of a project. Typical
1342 examples are the setup of platform-specific compiler options, or the use of
1343 a debug and a release mode (the former would activate the generation of debug
1344 information, when the second will focus on improving code optimization).
1346 Let's enhance our example to support a debug and a release modes.The issue is to
1347 let the user choose what kind of system he is building:
1348 use @option{-g} as compiler switches in debug mode and @option{-O2}
1349 in release mode. We will also setup the projects so that we do not share the
1350 same object directory in both modes, otherwise switching from one to the other
1351 might trigger more recompilations than needed or mix objects from the 2 modes.
1353 One naive approach is to create two different project files, say
1354 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1355 attributes as explained in previous sections. This solution does not scale well,
1356 because in presence of multiple projects depending on each other,
1357 you will also have to duplicate the complete hierarchy and adapt the project
1358 files to point to the right copies.
1361 Instead, project files support the notion of scenarios controlled
1362 by external values. Such values can come from several sources (in decreasing
1366 @item @b{Command line}:
1368 When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1369 extra @option{-X} switches to define the external value. In
1370 our case, the command line might look like
1373 gnatmake -Pbuild.gpr -Xmode=debug
1374 or gnatmake -Pbuild.gpr -Xmode=release
1377 @item @b{^Environment variables^Logical names^}:
1378 When the external value does not come from the command line, it can come from
1379 the value of ^environment variables^logical names^ of the appropriate name.
1380 In our case, if ^an environment variable^a logical name^ called "mode"
1381 exist, its value will be taken into account.
1383 @item @b{External function second parameter}
1387 @cindex @code{external}
1388 We now need to get that value in the project. The general form is to use
1389 the predefined function @b{external} which returns the current value of
1390 the external. For instance, we could setup the object directory to point to
1391 either @file{obj/debug} or @file{obj/release} by changing our project to
1393 @smallexample @c projectfile
1395 for Object_Dir use "obj/" & external ("mode", "debug");
1401 The second parameter to @code{external} is optional, and is the default
1402 value to use if "mode" is not set from the command line or the environment.
1404 In order to set the switches according to the different scenarios, other
1405 constructs have to be introduced such as typed variables and case statements.
1407 @cindex typed variable
1408 @cindex case statement
1409 A @b{typed variable} is a variable that
1410 can take only a limited number of values, similar to an enumeration in Ada.
1411 Such a variable can then be used in a @b{case statement} and create conditional
1412 sections in the project. The following example shows how this can be done:
1414 @smallexample @c projectfile
1416 type Mode_Type is ("debug", "release"); -- all possible values
1417 Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1422 for Switches ("Ada") use ("-g");
1424 for Switches ("Ada") use ("-O2");
1431 The project has suddenly grown in size, but has become much more flexible.
1432 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1433 any other value is read from the environment, an error is reported and the
1434 project is considered as invalid.
1436 The @code{Mode} variable is initialized with an external value
1437 defaulting to @code{"debug"}. This default could be omitted and that would
1438 force the user to define the value. Finally, we can use a case statement to set the
1439 switches depending on the scenario the user has chosen.
1441 Most aspects of the projects can depend on scenarios. The notable exception
1442 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1444 Scenarios work the same way with @b{project hierarchies}: you can either
1445 duplicate a variable similar to @code{Mode} in each of the project (as long
1446 as the first argument to @code{external} is always the same and the type is
1447 the same), or simply set the variable in the @file{shared.gpr} project
1448 (@pxref{Sharing Between Projects}).
1450 @c ---------------------------------------------
1451 @node Library Projects
1452 @section Library Projects
1453 @c ---------------------------------------------
1456 So far, we have seen examples of projects that create executables. However,
1457 it is also possible to create libraries instead. A @b{library} is a specific
1458 type of subsystem where, for convenience, objects are grouped together
1459 using system-specific means such as archives or windows DLLs.
1461 Library projects provide a system- and language-independent way of building both @b{static}
1462 and @b{dynamic} libraries. They also support the concept of @b{standalone
1463 libraries} (SAL) which offers two significant properties: the elaboration
1464 (e.g. initialization) of the library is either automatic or very simple;
1466 implementation part of the library implies minimal post-compilation actions on
1467 the complete system and potentially no action at all for the rest of the
1468 system in the case of dynamic SALs.
1470 The GNAT Project Manager takes complete care of the library build, rebuild and
1471 installation tasks, including recompilation of the source files for which
1472 objects do not exist or are not up to date, assembly of the library archive, and
1473 installation of the library (i.e., copying associated source, object and
1474 @file{ALI} files to the specified location).
1477 * Building Libraries::
1478 * Using Library Projects::
1479 * Stand-alone Library Projects::
1480 * Installing a library with project files::
1483 @c ---------------------------------------------
1484 @node Building Libraries
1485 @subsection Building Libraries
1486 @c ---------------------------------------------
1489 Let's enhance our example and transform the @code{logging} subsystem into a
1490 library.In orer to do so, a few changes need to be made to @file{logging.gpr}.
1491 A number of specific attributes needs to be defined: at least @code{Library_Name}
1492 and @code{Library_Dir}; in addition, a number of other attributes can be used
1493 to specify specific aspects of the library. For readablility, it is also
1494 recommended (although not mandatory), to use the qualifier @code{library} in
1495 front of the @code{project} keyword.
1498 @item @b{Library_Name}:
1499 @cindex @code{Library_Name}
1500 This attribute is the name of the library to be built. There is no
1501 restriction on the name of a library imposed by the project manager;
1502 however, there may be system specific restrictions on the name.
1503 In general, it is recommended to stick to alphanumeric characters
1504 (and possibly underscores) to help portability.
1506 @item @b{Library_Dir}:
1507 @cindex @code{Library_Dir}
1508 This attribute is the path (absolute or relative) of the directory where
1509 the library is to be installed. In the process of building a library,
1510 the sources are compiled, the object files end up in the explicit or
1511 implicit @code{Object_Dir} directory. When all sources of a library
1512 are compiled, some of the compilation artifacts, including the library itself,
1513 are copied to the library_dir directory. This directory must exists and be
1514 writable. It must also be different from the object directory so that cleanup
1515 activities in the Library_Dir do not affect recompilation needs.
1519 Here is the new version of @file{logging.gpr} that makes it a library:
1521 @smallexample @c projectfile
1522 library project Logging is -- "library" is optional
1523 for Library_Name use "logging"; -- will create "liblogging.a" on Unix
1524 for Object_Dir use "obj";
1525 for Library_Dir use "lib"; -- different from object_dir
1530 Once the above two attributes are defined, the library project is valid and
1531 is enough for building a library with default characteristics.
1532 Other library-related attributes can be used to change the defaults:
1535 @item @b{Library_Kind}:
1536 @cindex @code{Library_Kind}
1537 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1538 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1539 which kind of library should be build (the default is to build a
1540 static library, that is an archive of object files that can potentially
1541 be linked into a static executable). When the library is set to be dynamic,
1542 a separate image is created that will be loaded independnently, usually
1543 at the start of the main program execution. Support for dynamic libraries is
1544 very platform specific, for instance on Windows it takes the form of a DLL
1545 while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1546 @file{.so}. Library project files, on the other hand, can be written in
1547 a platform independant way so that the same project file can be used to build
1548 a library on different Oses.
1550 If you need to build both a static and a dynamic library, it is recommended
1551 use two different object directories, since in some cases some extra code
1552 needs to be generated for the latter. For such cases, one can
1553 either define two different project files, or a single one which uses scenarios
1554 to indicate at the various kinds of library to be build and their
1555 corresponding object_dir.
1557 @cindex @code{Library_ALI_Dir}
1558 @item @b{Library_ALI_Dir}:
1559 This attribute may be specified to indicate the directory where the ALI
1560 files of the library are installed. By default, they are copied into the
1561 @code{Library_Dir} directory, but as for the executables where we have a
1562 separate @code{Exec_Dir} attribute, you might want to put them in a separate
1563 directory since there can be hundreds of them. The same restrictions as for
1564 the @code{Library_Dir} attribute apply.
1566 @cindex @code{Library_Version}
1567 @item @b{Library_Version}:
1568 This attribute is platform dependent, and has no effect on VMS and Windows.
1569 On Unix, it is used only for dynamic libraries as the internal
1570 name of the library (the @code{"soname"}). If the library file name (built
1571 from the @code{Library_Name}) is different from the @code{Library_Version},
1572 then the library file will be a symbolic link to the actual file whose name
1573 will be @code{Library_Version}. This follows the usual installation schemes
1574 for dynamic libraries on many Unix systems.
1576 @smallexample @c projectfile
1580 for Library_Dir use "lib";
1581 for Library_Name use "logging";
1582 for Library_Kind use "dynamic";
1583 for Library_Version use "liblogging.so." & Version;
1589 After the compilation, the directory @file{lib} will contain both a
1590 @file{libdummy.so.1} library and a symbolic link to it called
1593 @cindex @code{Library_GCC}
1594 @item @b{Library_GCC}:
1595 This attribute is the name of the tool to use instead of "gcc" to link shared
1596 libraries. A common use of this attribute is to define a wrapper script that
1597 accomplishes specific actions before calling gcc (which itself is calling the
1598 linker to build the library image).
1600 @item @b{Library_Options}:
1601 @cindex @code{Library_Options}
1602 This attribute may be used to specified additional switches (last switches)
1603 when linking a shared library.
1605 @item @b{Leading_Library_Options}:
1606 @cindex @code{Leading_Library_Options}
1607 This attribute, that is taken into account only by @command{gprbuild}, may be
1608 used to specified leading options (first switches) when linking a shared
1611 @cindex @code{Linker_Options}
1612 @item @b{Linker.Linker_Options}:
1613 This attribute specifies additional switches to be given to the linker when
1614 linking an executable. It is ignored when defined in the main project and
1615 taken into account in all other projects that are imported directly or
1616 indirectly. These switches complement the @code{Linker.Switches}
1617 defined in the main project. This is useful when a particular subsystem
1618 depends on an external library: adding this dependency as a
1619 @code{Linker_Options} in the project of the subsystem is more convenient than
1620 adding it to all the @code{Linker.Switches} of the main projects that depend
1621 upon this subsystem.
1625 @c ---------------------------------------------
1626 @node Using Library Projects
1627 @subsection Using Library Projects
1628 @c ---------------------------------------------
1631 When the builder detects that a project file is a library project file, it
1632 recompiles all sources of the project that need recompilation and rebuild the
1633 library if any of the sources have been recompiled. It then groups all object
1634 files into a single file, which is a shared or a static library. This library
1635 can later on be linked with multiple executables. Note that the use
1636 of shard libraries reduces the size of the final executable and can also reduce
1637 the memory footprint at execution time when the library is shared among several
1640 It is also possible to build @b{multi-language libraries}. When using
1641 @command{gprbuild} as a builder, multi-language library projects allow naturally
1642 the creation of multi-language libraries . @command{gnatmake}, does n ot try to
1643 compile non Ada sources. However, when the project is multi-language, it will
1644 automatically link all object files found in the object directory, whether or
1645 not they were compiled from an Ada source file. This specific behavior does not
1646 apply to Ada-only projects which only take into account the objects
1647 corresponding to the sources of the project.
1649 A non-library project can import a library project. When the builder is invoked
1650 on the former, the library of the latter is only rebuilt when absolutely
1651 necessary. For instance, if a unit of the
1652 library is not up-to-date but non of the executables need this unit, then the
1653 unit is not recompiled and the library is not reassembled.
1654 For instance, let's assume in our example that logging has the following
1655 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1656 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1657 @file{liblogging} will be rebuilt when compiling all the sources of
1658 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1659 include a @code{"with Log1"}.
1661 To ensure that all the sources in the @code{Logging} library are
1662 up to date, and that all the sources of @code{Build} are also up to date,
1663 the following two commands needs to be used:
1666 gnatmake -Plogging.gpr
1667 gnatmake -Pbuild.gpr
1671 All @file{ALI} files will also be copied from the object directory to the
1672 library directory. To build executables, @command{gnatmake} will use the
1673 library rather than the individual object files.
1676 Library projects can also be useful to describe a library that need to be used
1677 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1678 of the library sources are not available. Such library projects need simply to
1679 use the @code{Externally_Built} attribute as in the example below:
1681 @smallexample @c projectfile
1682 library project Extern_Lib is
1683 for Languages use ("Ada", "C");
1684 for Source_Dirs use ("lib_src");
1685 for Library_Dir use "lib2";
1686 for Library_Kind use "dynamic";
1687 for Library_Name use "l2";
1688 for Externally_Built use "true"; -- <<<<
1693 In the case of externally built libraries, the @code{Object_Dir}
1694 attribute does not need to be specified because it will never be
1697 The main effect of using such an externally built library project is mostly to
1698 affect the linker command in order to reference the desired library. It can
1699 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1700 in the project corresponding to the subsystem needing this external library.
1701 This latter method is more straightforward in simple cases but when several
1702 subsystems depend upon the same external library, finding the proper place
1703 for the @code{Linker.Linker_Options} might not be easy and if it is
1704 not placed properly, the final link command is likely to present ordering issues.
1705 In such a situation, it is better to use the externally built library project
1706 so that all other subsystems depending on it can declare this dependency thanks
1707 to a project @code{with} clause, which in turn will trigger the builder to find
1708 the proper order of libraries in the final link command.
1711 @c ---------------------------------------------
1712 @node Stand-alone Library Projects
1713 @subsection Stand-alone Library Projects
1714 @c ---------------------------------------------
1717 @cindex standalone libraries
1718 A @b{stand-alone library} is a library that contains the necessary code to
1719 elaborate the Ada units that are included in the library. A stand-alone
1720 library is a convenient way to add an Ada subsystem to a more global system
1721 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1722 transparent. However, stand-alone libraries are also useful when the main is in
1723 Ada: they provide a means for minimizing relinking & redeployement of complex
1724 systems when localized changes are made.
1726 The most proeminent characteristic of a stand-alone library is that it offers a
1727 distinction between interface units and implementation units. Only the former
1728 are visible to units outside the library. A stand-alone library project is thus
1729 characterised by a third attribute, @b{Library_Interface}, in addition to the
1730 two attributes that make a project a Library Project (@code{Library_Name} and
1731 @code{Library_Dir}).
1734 @item @b{Library_Interface}:
1735 @cindex @code{Library_Interface}
1736 This attribute defines an explicit subset of the units of the project.
1737 Projects importing this library project may only "with" units whose sources
1738 are listed in the @code{Library_Interface}. Other sources are considered
1739 implementation units.
1741 @smallexample @c projectfile
1743 for Library_Dir use "lib";
1744 for Library_Name use "loggin";
1745 for Library_Interface use ("lib1", "lib2"); -- unit names
1751 In order to include the elaboration code in the stand-alone library, the binder
1752 is invoked on the closure of the library units creating a package whose name
1753 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1754 This binder-generated package includes @b{initialization} and @b{finalization}
1755 procedures whose names depend on the library name (@code{logginginit} and
1756 @code{loggingfinal} in the example). The object corresponding to this package is
1757 included in the library.
1760 @item @b{Library_Auto_Init}:
1761 @cindex @code{Library_Auto_Init}
1762 A dynamic stand-alone Library is automatically initialized
1763 if automatic initialization of Stand-alone Libraries is supported on the
1764 platform and if attribute @b{Library_Auto_Init} is not specified or
1765 is specified with the value "true". A static Stand-alone Library is never
1766 automatically initialized. Specifying "false" for this attribute
1767 prevent automatic initialization.
1769 When a non-automatically initialized stand-alone library is used in an
1770 executable, its initialization procedure must be called before any service of
1771 the library is used. When the main subprogram is in Ada, it may mean that the
1772 initialization procedure has to be called during elaboration of another
1775 @item @b{Library_Dir}:
1776 @cindex @code{Library_Dir}
1777 For a stand-alone library, only the @file{ALI} files of the interface units
1778 (those that are listed in attribute @code{Library_Interface}) are copied to
1779 the library directory. As a consequence, only the interface units may be
1780 imported from Ada units outside of the library. If other units are imported,
1781 the binding phase will fail.
1783 @item @b{Binder.Default_Switches}:
1784 When a stand-alone library is bound, the switches that are specified in
1785 the attribute @b{Binder.Default_Switches ("Ada")} are
1786 used in the call to @command{gnatbind}.
1788 @item @b{Library_Src_Dir}:
1789 @cindex @code{Library_Src_Dir}
1790 This attribute defines the location (absolute or relative to the project
1791 directory) where the sources of the interface units are copied at
1793 These sources includes the specs of the interface units along with the closure
1794 of sources necessary to compile them successfully. That may include bodies and
1795 subunits, when pragmas @code{Inline} are used, or when there is a generic
1796 units in the spec. This directory cannot point to the object directory or
1797 one of the source directories, but it can point to the library directory,
1798 which is the default value for this attribute.
1800 @item @b{Library_Symbol_Policy}:
1801 @cindex @code{Library_Symbol_Policy}
1802 This attribute controls the export of symbols and, on some platforms (like
1803 VMS) that have the notions of major and minor IDs built in the library
1804 files, it controls the setting of these IDs. It is not supported on all
1805 platforms (where it will just have no effect). It may have one of the
1809 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1810 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1811 is not defined, then it is equivalent to policy "autonomous". If there
1812 are exported symbols in the reference symbol file that are not in the
1813 object files of the interfaces, the major ID of the library is increased.
1814 If there are symbols in the object files of the interfaces that are not
1815 in the reference symbol file, these symbols are put at the end of the list
1816 in the newly created symbol file and the minor ID is increased.
1817 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1818 defined. The library will fail to build if the exported symbols in the
1819 object files of the interfaces do not match exactly the symbol in the
1821 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1822 The library will fail to build if there are symbols in the symbol file that
1823 are not in the exported symbols of the object files of the interfaces.
1824 Additional symbols in the object files are not added to the symbol file.
1825 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1826 must designate an existing file in the object directory. This symbol file
1827 is passed directly to the underlying linker without any symbol processing.
1831 @item @b{Library_Reference_Symbol_File}
1832 @cindex @code{Library_Reference_Symbol_File}
1833 This attribute may define the path name of a reference symbol file that is
1834 read when the symbol policy is either "compliant" or "controlled", on
1835 platforms that support symbol control, such as VMS, when building a
1836 stand-alone library. The path may be an absolute path or a path relative
1837 to the project directory.
1839 @item @b{Library_Symbol_File}
1840 @cindex @code{Library_Symbol_File}
1841 This attribute may define the name of the symbol file to be created when
1842 building a stand-alone library when the symbol policy is either "compliant",
1843 "controlled" or "restricted", on platforms that support symbol control,
1844 such as VMS. When symbol policy is "direct", then a file with this name
1845 must exist in the object directory.
1849 @c ---------------------------------------------
1850 @node Installing a library with project files
1851 @subsection Installing a library with project files
1852 @c ---------------------------------------------
1855 When using project files, library installation is part of the library build
1856 process. Thus no further action is needed in order to make use of the
1857 libraries that are built as part of the general application build. A usable
1858 version of the library is installed in the directory specified by the
1859 @code{Library_Dir} attribute of the library project file.
1861 You may want to install a library in a context different from where the library
1862 is built. This situation arises with third party suppliers, who may want
1863 to distribute a library in binary form where the user is not expected to be
1864 able to recompile the library. The simplest option in this case is to provide
1865 a project file slightly different from the one used to build the library, by
1866 using the @code{externally_built} attribute. @ref{Using Library Projects}
1868 @c ---------------------------------------------
1869 @node Project Extension
1870 @section Project Extension
1871 @c ---------------------------------------------
1874 During development of a large system, it is sometimes necessary to use
1875 modified versions of some of the source files, without changing the original
1876 sources. This can be achieved through the @b{project extension} facility.
1878 Suppose for instance that our example @code{Build} project is build every night
1879 for the whole team, in some shared directory. A developer usually need to work
1880 on a small part of the system, and might not want to have a copy of all the
1881 sources and all the object files (mostly because that would require too much
1882 disk space, time to recompile everything). He prefers to be able to override
1883 some of the source files in his directory, while taking advantage of all the
1884 object files generated at night.
1886 Another example can be taken from large software systems, where it is common to have
1887 multiple implementations of a common interface; in Ada terms, multiple
1888 versions of a package body for the same spec. For example, one implementation
1889 might be safe for use in tasking programs, while another might only be used
1890 in sequential applications. This can be modeled in GNAT using the concept
1891 of @emph{project extension}. If one project (the ``child'') @emph{extends}
1892 another project (the ``parent'') then by default all source files of the
1893 parent project are inherited by the child, but the child project can
1894 override any of the parent's source files with new versions, and can also
1895 add new files or remove unnecessary ones.
1896 This facility is the project analog of a type extension in
1897 object-oriented programming. Project hierarchies are permitted (an extending
1898 project may itself be extended), and a project that
1899 extends a project can also import other projects.
1901 A third example is that of using project extensions to provide different
1902 versions of the same system. For instance, assume that a @code{Common}
1903 project is used by two development branches. One of the branches has now
1904 been frozen, and no further change can be done to it or to @code{Common}.
1905 However, the other development branch still needs evolution of @code{Common}.
1906 Project extensions provide a flexible solution to create a new version
1907 of a subsystem while sharing and reusing as much as possible from the original
1910 A project extension inherits implicitly all the sources and objects from the
1911 project it extends. It is possible to create a new version of some of the
1912 sources in one of the additional source dirs of the extending project. Those new
1913 versions hide the original versions. Adding new sources or removing existing
1914 ones is also possible. Here is an example on how to extend the project
1915 @code{Build} from previous examples:
1917 @smallexample @c projectfile
1918 project Work extends "../bld/build.gpr" is
1923 The project after @b{extends} is the one being extended. As usual, it can be
1924 specified using an absolute path, or a path relative to any of the directories
1925 in the project path (@pxref{Project Dependencies}). This project does not
1926 specify source or object directories, so the default value for these attribute
1927 will be used that is to say the current directory (where project @code{Work} is
1928 placed). We can already compile that project with
1935 If no sources have been placed in the current directory, this command
1936 won't do anything, since this project does not change the
1937 sources it inherited from @code{Build}, therefore all the object files
1938 in @code{Build} and its dependencies are still valid and are reused
1941 Suppose we now want to supply an alternate version of @file{pack.adb}
1942 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
1943 We can create the new file Work's current directory (likely
1944 by copying the one from the @code{Build} project and making changes to
1945 it. If new packages are needed at the same time, we simply create
1946 new files in the source directory of the extending project.
1948 When we recompile, @command{gnatmake} will now automatically recompile
1949 this file (thus creating @file{pack.o} in the current directory) and
1950 any file that depends on it (thus creating @file{proc.o}). Finally, the
1951 executable is also linked locally.
1953 Note that we could have obtained the desired behavior using project import
1954 rather than project inheritance. A @code{base} project would contain the
1955 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
1956 import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
1957 cannot contain the original version of @file{pack.adb} otherwise there would be
1958 2 versions of the same unit in the closure of the project and this is not
1959 allowed. Generally speaking, it is not recommended to put the spec and the
1960 body of a unit in different projects since this affects their autonomy and
1963 In a project file that extends another project, it is possible to
1964 indicate that an inherited source is @b{not part} of the sources of the
1965 extending project. This is necessary sometimes when a package spec has
1966 been overridden and no longer requires a body: in this case, it is
1967 necessary to indicate that the inherited body is not part of the sources
1968 of the project, otherwise there will be a compilation error
1969 when compiling the spec.
1971 @cindex @code{Excluded_Source_Files}
1972 @cindex @code{Excluded_Source_List_File}
1973 For that purpose, the attribute @b{Excluded_Source_Files} is used.
1974 Its value is a list of file names.
1975 It is also possible to use attribute @code{Excluded_Source_List_File}.
1976 Its value is the path of a text file containing one file name per
1979 @smallexample @c @projectfile
1980 project Work extends "../bld/build.gpr" is
1981 for Source_Files use ("pack.ads");
1982 -- New spec of Pkg does not need a completion
1983 for Excluded_Source_Files use ("pack.adb");
1988 An extending project retains all the switches specified in the
1992 * Project Hierarchy Extension::
1995 @c ---------------------------------------------
1996 @node Project Hierarchy Extension
1997 @subsection Project Hierarchy Extension
1998 @c ---------------------------------------------
2001 One of the fundamental restrictions in project extension is the following:
2002 @b{A project is not allowed to import directly or indirectly at the same time an
2003 extending project and one of its ancestors}.
2005 By means of example, consider the following hierarchy of projects.
2008 a.gpr contains package A1
2009 b.gpr, imports a.gpr and contains B1, which depends on A1
2010 c.gpr, imports b.gpr and contains C1, which depends on B1
2014 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2015 create several extending projects:
2018 a_ext.gpr which extends a.gpr, and overrides A1
2019 b_ext.gpr which extends b.gpr and imports a_ext.gpr
2020 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2024 @smallexample @c projectfile
2025 project A_Ext extends "a.gpr" is
2026 for Source_Files use ("a1.adb", "a1.ads");
2030 project B_Ext extends "b.gpr" is
2034 project C_Ext extends "c.gpr" is
2035 for Source_Files use ("c1.adb");
2040 The extension @file{b_ext.gpr} is required, even though we are not overriding
2041 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2042 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2045 When extending a large system spanning multiple projects, it is often
2046 inconvenient to extend every project in the hierarchy that is impacted by a
2047 small change introduced in a low layer. In such cases, it is possible to create
2048 an @b{implicit extension} of entire hierarchy using @b{extends all}
2051 When the project is extended using @code{extends all} inheritance, all projects
2052 that are imported by it, both directly and indirectly, are considered virtually
2053 extended. That is, the project manager creates implicit projects
2054 that extend every project in the hierarchy; all these implicit projects do not
2055 control sources on their own and use the object directory of
2056 the "extending all" project.
2058 It is possible to explicitly extend one or more projects in the hierarchy
2059 in order to modify the sources. These extending projects must be imported by
2060 the "extending all" project, which will replace the corresponding virtual
2061 projects with the explicit ones.
2063 When building such a project hierarchy extension, the project manager will
2064 ensure that both modified sources and sources in implicit extending projects
2065 that depend on them, are recompiled.
2067 Thus, in our example we could create the following projects instead:
2070 a_ext.gpr, extends a.gpr and overrides A1
2071 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2076 @smallexample @c projectfile
2077 project A_Ext extends "a.gpr" is
2078 for Source_Files use ("a1.adb", "a1.ads");
2082 project C_Ext extends all "c.gpr" is
2083 for Source_Files use ("c1.adb");
2088 When building project @file{c_ext.gpr}, the entire modified project space is
2089 considered for recompilation, including the sources of @file{b.gpr} that are
2090 impacted by the changes in @code{A1} and @code{C1}.
2092 @c ---------------------------------------------
2093 @node Project File Reference
2094 @section Project File Reference
2095 @c ---------------------------------------------
2098 This section describes the syntactic structure of project files, the various
2099 constructs that can be used. Finally, it ends with a summary of all available
2103 * Project Declaration::
2104 * Qualified Projects::
2109 * Typed String Declaration::
2115 @c ---------------------------------------------
2116 @node Project Declaration
2117 @subsection Project Declaration
2118 @c ---------------------------------------------
2121 Project files have an Ada-like syntax. The minimal project file is:
2123 @smallexample @c projectfile
2131 The identifier @code{Empty} is the name of the project.
2132 This project name must be present after the reserved
2133 word @code{end} at the end of the project file, followed by a semi-colon.
2135 @b{Identifiers} (ie the user-defined names such as project or variable names)
2136 have the same syntax as Ada identifiers: they must start with a letter,
2137 and be followed by zero or more letters, digits or underscore characters;
2138 it is also illegal to have two underscores next to each other. Identifiers
2139 are always case-insensitive ("Name" is the same as "name").
2142 simple_name ::= identifier
2143 name ::= simple_name @{ . simple_name @}
2147 @b{Strings} are used for values of attributes or as indexes for these
2148 attributes. They are in general case sensitive, except when noted
2149 otherwise (in particular, strings representing file names will be case
2150 insensitive on some systems, so that "file.adb" and "File.adb" both
2151 represent the same file).
2153 @b{Reserved words} are the same as for standard Ada 95, and cannot
2154 be used for identifiers. In particular, the following words are currently
2155 used in project files, but others could be added later on. In bold are the
2156 extra reserved words in project files: @code{all, at, case, end, for, is,
2157 limited, null, others, package, renames, type, use, when, with, @b{extends},
2158 @b{external}, @b{project}}.
2160 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2161 hyphens through the end of the line.
2163 A project may be an @b{independent project}, entirely defined by a single
2164 project file. Any source file in an independent project depends only
2165 on the predefined library and other source files in the same project.
2166 But a project may also depend on other projects, either by importing them
2167 through @b{with clauses}, or by @b{extending} at most one other project. Both
2168 types of dependency can be used in the same project.
2170 A path name denotes a project file. It can be absolute or relative.
2171 An absolute path name includes a sequence of directories, in the syntax of
2172 the host operating system, that identifies uniquely the project file in the
2173 file system. A relative path name identifies the project file, relative
2174 to the directory that contains the current project, or relative to a
2175 directory listed in the environment variables ADA_PROJECT_PATH and
2176 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2177 operating system are case sensitive. As a special case, the directory
2178 separator can always be "/" even on Windows systems, so that project files
2179 can be made portable across architectures.
2180 The syntax of the environment variable ADA_PROJECT_PATH and
2181 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2182 semicolons on Windows.
2184 A given project name can appear only once in a context clause.
2186 It is illegal for a project imported by a context clause to refer, directly
2187 or indirectly, to the project in which this context clause appears (the
2188 dependency graph cannot contain cycles), except when one of the with clause
2189 in the cycle is a @b{limited with}.
2190 @c ??? Need more details here
2192 @smallexample @c projectfile
2193 with "other_project.gpr";
2194 project My_Project extends "extended.gpr" is
2199 These dependencies form a @b{directed graph}, potentially cyclic when using
2200 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
2203 A project's @b{immediate sources} are the source files directly defined by
2204 that project, either implicitly by residing in the project source directories,
2205 or explicitly through any of the source-related attributes.
2206 More generally, a project sources are the immediate sources of the project
2207 together with the immediate sources (unless overridden) of any
2208 project on which it depends directly or indirectly.
2210 A @b{project hierarchy} can be created, where projects are children of
2211 other projects. The name of such a child project must be @code{Parent.Child},
2212 where @code{Parent} is the name of the parent project. In particular, this
2213 makes all @code{with} clauses of the parent project automatically visible
2214 in the child project.
2217 project ::= context_clause project_declaration
2219 context_clause ::= @{with_clause@}
2220 with_clause ::= @i{with} path_name @{ , path_name @} ;
2221 path_name ::= string_literal
2223 project_declaration ::= simple_project_declaration | project_extension
2224 simple_project_declaration ::=
2225 @i{project} @i{<project_>}name @i{is}
2226 @{declarative_item@}
2227 @i{end} <project_>simple_name;
2230 @c ---------------------------------------------
2231 @node Qualified Projects
2232 @subsection Qualified Projects
2233 @c ---------------------------------------------
2236 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
2237 is identifiers or reserved words, to qualify the project.
2238 The current list of qualifiers is:
2241 @item @b{abstract}: qualifies a project with no sources. Such a
2242 project must either have no declaration of attributes @code{Source_Dirs},
2243 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
2244 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
2245 as empty. If it extends another project, the project it extends must also be a
2246 qualified abstract project.
2247 @item @b{standard}: a standard project is a non library project with sources.
2248 This is the default (implicit) qualifier.
2249 @item @b{aggregate}: for future extension
2250 @item @b{aggregate library}: for future extension
2251 @item @b{library}: a library project must declare both attributes
2252 @code{Library_Name} and @code{Library_Dir}.
2253 @item @b{configuration}: a configuration project cannot be in a project tree.
2254 It describes compilers and other tools to @code{gprbuild}.
2258 @c ---------------------------------------------
2260 @subsection Declarations
2261 @c ---------------------------------------------
2264 Declarations introduce new entities that denote types, variables, attributes,
2265 and packages. Some declarations can only appear immediately within a project
2266 declaration. Others can appear within a project or within a package.
2269 declarative_item ::= simple_declarative_item
2270 | typed_string_declaration
2271 | package_declaration
2273 simple_declarative_item ::= variable_declaration
2274 | typed_variable_declaration
2275 | attribute_declaration
2279 empty_declaration ::= @i{null} ;
2283 An empty declaration is allowed anywhere a declaration is allowed. It has
2286 @c ---------------------------------------------
2288 @subsection Packages
2289 @c ---------------------------------------------
2292 A project file may contain @b{packages}, that group attributes (typically
2293 all the attributes that are used by one of the GNAT tools).
2295 A package with a given name may only appear once in a project file.
2296 The following packages are currently supported in project files
2297 (See @pxref{Attributes} for the list of attributes that each can contain).
2301 This package specifies characteristics useful when invoking the binder either
2302 directly via the @command{gnat} driver or when using a builder such as
2303 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
2305 This package specifies the compilation options used when building an
2306 executable or a library for a project. Most of the options should be
2307 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
2308 but there are some general options that should be defined in this
2309 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
2312 This package specifies the options used when calling the checking tool
2313 @command{gnatcheck} via the @command{gnat} driver. Its attribute
2314 @b{Default_Switches} has the same semantics as for the package
2315 @code{Builder}. The first string should always be @code{-rules} to specify
2316 that all the other options belong to the @code{-rules} section of the
2317 parameters to @command{gnatcheck}.
2319 This package specifies the compilation options used by the compiler for
2320 each languages. @xref{Tools Options in Project Files}.
2321 @item Cross_Reference
2322 This package specifies the options used when calling the library tool
2323 @command{gnatxref} via the @command{gnat} driver. Its attributes
2324 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2325 package @code{Builder}.
2327 This package specifies the options used when calling the tool
2328 @command{gnatelim} via the @command{gnat} driver. Its attributes
2329 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2330 package @code{Builder}.
2332 This package specifies the options used when calling the search tool
2333 @command{gnatfind} via the @command{gnat} driver. Its attributes
2334 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2335 package @code{Builder}.
2337 This package the options to use when invoking @command{gnatls} via the
2338 @command{gnat} driver.
2340 This package specifies the options used when calling the tool
2341 @command{gnatstub} via the @command{gnat} driver. Its attributes
2342 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2343 package @code{Builder}.
2345 This package specifies the options used when starting an integrated
2346 development environment, for instance @command{GPS} or @command{Gnatbench}.
2347 @xref{The Development Environments}.
2349 This package specifies the options used by the linker.
2350 @xref{Main Subprograms}.
2352 This package specifies the options used when calling the tool
2353 @command{gnatmetric} via the @command{gnat} driver. Its attributes
2354 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2355 package @code{Builder}.
2357 This package specifies the naming conventions that apply
2358 to the source files in a project. In particular, these conventions are
2359 used to automatically find all source files in the source directories,
2360 or given a file name to find out its language for proper processing.
2361 @xref{Naming Schemes}.
2362 @item Pretty_Printer
2363 This package specifies the options used when calling the formatting tool
2364 @command{gnatpp} via the @command{gnat} driver. Its attributes
2365 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2366 package @code{Builder}.
2368 This package specifies the options used when calling the tool
2369 @command{gnatstack} via the @command{gnat} driver. Its attributes
2370 @b{Default_Switches} and @b{Switches} have the same semantics as for the
2371 package @code{Builder}.
2373 This package specifies the options used when calling the tool
2374 @command{gnatsync} via the @command{gnat} driver.
2378 In its simplest form, a package may be empty:
2380 @smallexample @c projectfile
2390 A package may contain @b{attribute declarations},
2391 @b{variable declarations} and @b{case constructions}, as will be
2394 When there is ambiguity between a project name and a package name,
2395 the name always designates the project. To avoid possible confusion, it is
2396 always a good idea to avoid naming a project with one of the
2397 names allowed for packages or any name that starts with @code{gnat}.
2399 A package can also be defined by a @b{renaming declaration}. The new package
2400 renames a package declared in a different project file, and has the same
2401 attributes as the package it renames. The name of the renamed package
2402 must be the same as the name of the renaming package. The project must
2403 contain a package declaration with this name, and the project
2404 must appear in the context clause of the current project, or be its parent
2405 project. It is not possible to add or override attributes to the renaming
2406 project. If you need to do so, you should use an @b{extending declaration}
2409 Packages that are renamed in other project files often come from project files
2410 that have no sources: they are just used as templates. Any modification in the
2411 template will be reflected automatically in all the project files that rename
2412 a package from the template. This is a very common way to share settings
2415 Finally, a package can also be defined by an @b{extending declaration}. This is
2416 similar to a @b{renaming declaration}, except that it is possible to add or
2417 override attributes.
2420 package_declaration ::= package_spec | package_renaming | package_extension
2422 @i{package} @i{<package_>}simple_name @i{is}
2423 @{simple_declarative_item@}
2424 @i{end} package_identifier ;
2425 package_renaming ::==
2426 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
2427 package_extension ::==
2428 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
2429 @{simple_declarative_item@}
2430 @i{end} package_identifier ;
2433 @c ---------------------------------------------
2435 @subsection Expressions
2436 @c ---------------------------------------------
2439 An expression is any value that can be assigned to an attribute or a
2440 variable. It is either a litteral value, or a construct requiring runtime
2441 computation by the project manager. In a project file, the computed value of
2442 an expression is either a string or a list of strings.
2444 A string value is one of:
2446 @item A literal string, for instance @code{"comm/my_proj.gpr"}
2447 @item The name of a variable that evaluates to a string (@pxref{Variables})
2448 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
2449 @item An external reference (@pxref{External Values})
2450 @item A concatenation of the above, as in @code{"prefix_" & Var}.
2455 A list of strings is one of the following:
2458 @item A parenthesized comma-separated list of zero or more string expressions, for
2459 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
2460 @item The name of a variable that evaluates to a list of strings
2461 @item The name of an attribute that evaluates to a list of strings
2462 @item A concatenation of a list of strings and a string (as defined above), for
2463 instance @code{("A", "B") & "C"}
2464 @item A concatenation of two lists of strings
2469 The following is the grammar for expressions
2472 string_literal ::= "@{string_element@}" -- Same as Ada
2473 string_expression ::= string_literal
2476 | attribute_reference
2477 | ( string_expression @{ & string_expression @} )
2478 string_list ::= ( string_expression @{ , string_expression @} )
2479 | @i{string_variable}_name
2480 | @i{string_}attribute_reference
2481 term ::= string_expression | string_list
2482 expression ::= term @{ & term @} -- Concatenation
2486 Concatenation involves strings and list of strings. As soon as a list of
2487 strings is involved, the result of the concatenation is a list of strings. The
2488 following Ada declarations show the existing operators:
2490 @smallexample @c ada
2491 function "&" (X : String; Y : String) return String;
2492 function "&" (X : String_List; Y : String) return String_List;
2493 function "&" (X : String_List; Y : String_List) return String_List;
2497 Here are some specific examples:
2499 @smallexample @c projectfile
2501 List := () & File_Name; -- One string in this list
2502 List2 := List & (File_Name & ".orig"); -- Two strings
2503 Big_List := List & Lists2; -- Three strings
2504 Illegal := "gnat.adc" & List2; -- Illegal, must start with list
2508 @c ---------------------------------------------
2509 @node External Values
2510 @subsection External Values
2511 @c ---------------------------------------------
2514 An external value is an expression whose value is obtained from the command
2515 that invoked the processing of the current project file (typically a
2516 gnatmake or gprbuild command).
2518 There are two kinds of external values, one that returns a single string, and
2519 one that returns a string list.
2521 The syntax of a single string external value is:
2524 external_value ::= @i{external} ( string_literal [, string_literal] )
2528 The first string_literal is the string to be used on the command line or
2529 in the environment to specify the external value. The second string_literal,
2530 if present, is the default to use if there is no specification for this
2531 external value either on the command line or in the environment.
2533 Typically, the external value will either exist in the
2534 ^environment variables^logical name^
2535 or be specified on the command line through the
2536 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
2537 are specified, then the command line value is used, so that a user can more
2538 easily override the value.
2540 The function @code{external} always returns a string. It is an error if the
2541 value was not found in the environment and no default was specified in the
2542 call to @code{external}.
2544 An external reference may be part of a string expression or of a string
2545 list expression, and can therefore appear in a variable declaration or
2546 an attribute declaration.
2548 Most of the time, this construct is used to initialize typed variables, which
2549 are then used in @b{case} statements to control the value assigned to
2550 attributes in various scenarios. Thus such variables are often called
2551 @b{scenario variables}.
2553 The syntax for a string list external value is:
2556 external_value ::= @i{external_as_list} ( string_literal , string_literal )
2560 The first string_literal is the string to be used on the command line or
2561 in the environment to specify the external value. The second string_literal is
2562 the separator between each component of the string list.
2564 If the external value does not exist in the environment or on the command line,
2565 the result is an empty list. This is also the case, if the separator is an
2566 empty string or if the external value is only one separator.
2568 Any separator at the beginning or at the end of the external value is
2569 discarded. Then, if there is no separator in the external vaue, the result is
2570 a string list with only one string. Otherwise, any string between the biginning
2571 and the first separator, between two consecutive separators and between the
2572 last separator and the end are components of the string list.
2575 @i{external_as_list} ("SWITCHES", ",")
2579 If the external value is "-O2,-g", the result is ("-O2", "-g").
2581 If the external value is ",-O2,-g,", the result is also ("-O2", "-g").
2583 if the external value is "-gnav", the result is ("-gnatv").
2585 If the external value is ",,", the result is ("").
2587 If the external value is ",", the result is (), the empty string list.
2589 @c ---------------------------------------------
2590 @node Typed String Declaration
2591 @subsection Typed String Declaration
2592 @c ---------------------------------------------
2595 A @b{type declaration} introduces a discrete set of string literals.
2596 If a string variable is declared to have this type, its value
2597 is restricted to the given set of literals. These are the only named
2598 types in project files. A string type may only be declared at the project
2599 level, not inside a package.
2602 typed_string_declaration ::=
2603 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
2607 The string literals in the list are case sensitive and must all be different.
2608 They may include any graphic characters allowed in Ada, including spaces.
2609 Here is an example of a string type declaration:
2611 @smallexample @c projectfile
2612 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
2616 Variables of a string type are called @b{typed variables}; all other
2617 variables are called @b{untyped variables}. Typed variables are
2618 particularly useful in @code{case} constructions, to support conditional
2619 attribute declarations. (@pxref{Case Statements}).
2621 A string type may be referenced by its name if it has been declared in the same
2622 project file, or by an expanded name whose prefix is the name of the project
2623 in which it is declared.
2625 @c ---------------------------------------------
2627 @subsection Variables
2628 @c ---------------------------------------------
2631 @b{Variables} store values (strings or list of strings) and can appear
2632 as part of an expression. The declaration of a variable creates the
2633 variable and assigns the value of the expression to it. The name of the
2634 variable is available immediately after the assignment symbol, if you
2635 need to reuse its old value to compute the new value. Before the completion
2636 of its first declaration, the value of a variable defaults to the empty
2639 A @b{typed} variable can be used as part of a @b{case} expression to
2640 compute the value, but it can only be declared once in the project file,
2641 so that all case statements see the same value for the variable. This
2642 provides more consistency and makes the project easier to understand.
2643 The syntax for its declaration is identical to the Ada syntax for an
2644 object declaration. In effect, a typed variable acts as a constant.
2646 An @b{untyped} variable can be declared and overridden multiple times
2647 within the same project. It is declared implicitly through an Ada
2648 assignment. The first declaration establishes the kind of the variable
2649 (string or list of strings) and successive declarations must respect
2650 the initial kind. Assignments are executed in the order in which they
2651 appear, so the new value replaces the old one and any subsequent reference
2652 to the variable uses the new value.
2654 A variable may be declared at the project file level, or within a package.
2657 typed_variable_declaration ::=
2658 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
2659 variable_declaration ::= @i{<variable_>}simple_name := expression;
2663 Here are some examples of variable declarations:
2665 @smallexample @c projectfile
2667 This_OS : OS := external ("OS"); -- a typed variable declaration
2668 That_OS := "GNU/Linux"; -- an untyped variable declaration
2670 Name := "readme.txt";
2671 Save_Name := Name & ".saved";
2674 List_With_One_Element := ("-gnaty");
2675 List_With_Two_Elements := List_With_One_Element & "-gnatg";
2676 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
2681 A @b{variable reference} may take several forms:
2684 @item The simple variable name, for a variable in the current package (if any)
2685 or in the current project
2686 @item An expanded name, whose prefix is a context name.
2691 A @b{context} may be one of the following:
2694 @item The name of an existing package in the current project
2695 @item The name of an imported project of the current project
2696 @item The name of an ancestor project (i.e., a project extended by the current
2697 project, either directly or indirectly)
2698 @item An expanded name whose prefix is an imported/parent project name, and
2699 whose selector is a package name in that project.
2703 @c ---------------------------------------------
2705 @subsection Attributes
2706 @c ---------------------------------------------
2709 A project (and its packages) may have @b{attributes} that define
2710 the project's properties. Some attributes have values that are strings;
2711 others have values that are string lists.
2714 attribute_declaration ::=
2715 simple_attribute_declaration | indexed_attribute_declaration
2716 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
2717 indexed_attribute_declaration ::=
2718 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
2719 attribute_designator ::=
2720 @i{<simple_attribute_>}simple_name
2721 | @i{<indexed_attribute_>}simple_name ( string_literal )
2725 There are two categories of attributes: @b{simple attributes}
2726 and @b{indexed attributes}.
2727 Each simple attribute has a default value: the empty string (for string
2728 attributes) and the empty list (for string list attributes).
2729 An attribute declaration defines a new value for an attribute, and overrides
2730 the previous value. The syntax of a simple attribute declaration is similar to
2731 that of an attribute definition clause in Ada.
2733 Some attributes are indexed. These attributes are mappings whose
2734 domain is a set of strings. They are declared one association
2735 at a time, by specifying a point in the domain and the corresponding image
2737 Like untyped variables and simple attributes, indexed attributes
2738 may be declared several times. Each declaration supplies a new value for the
2739 attribute, and replaces the previous setting.
2741 Here are some examples of attribute declarations:
2743 @smallexample @c projectfile
2744 -- simple attributes
2745 for Object_Dir use "objects";
2746 for Source_Dirs use ("units", "test/drivers");
2748 -- indexed attributes
2749 for Body ("main") use "Main.ada";
2750 for Switches ("main.ada") use ("-v", "-gnatv");
2751 for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
2753 -- indexed attributes copy (from package Builder in project Default)
2754 -- The package name must always be specified, even if it is the current
2756 for Default_Switches use Default.Builder'Default_Switches;
2760 Attributes references may be appear anywhere in expressions, and are used
2761 to retrieve the value previously assigned to the attribute. If an attribute
2762 has not been set in a given package or project, its value defaults to the
2763 empty string or the empty list.
2766 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
2767 attribute_prefix ::= @i{project}
2768 | @i{<project_>}simple_name
2769 | package_identifier
2770 | @i{<project_>}simple_name . package_identifier
2776 @smallexample @c projectfile
2778 Naming'Dot_Replacement
2779 Imported_Project'Source_Dirs
2780 Imported_Project.Naming'Casing
2781 Builder'Default_Switches ("Ada")
2785 The prefix of an attribute may be:
2788 @item @code{project} for an attribute of the current project
2789 @item The name of an existing package of the current project
2790 @item The name of an imported project
2791 @item The name of a parent project that is extended by the current project
2792 @item An expanded name whose prefix is imported/parent project name,
2793 and whose selector is a package name
2798 Legal attribute names are listed below, including the package in
2799 which they must be declared. These names are case-insensitive. The
2800 semantics for the attributes is explained in great details in other sections.
2802 The column @emph{index} indicates whether the attribute is an indexed attribute,
2803 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
2804 system (file). The text is between brackets ([]) if the index is optional.
2806 @multitable @columnfractions .3 .1 .2 .4
2807 @headitem Attribute Name @tab Value @tab Package @tab Index
2808 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
2809 @item Name @tab string @tab - @tab (Read-only, name of project)
2810 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
2811 @item Source_Files @tab list @tab - @tab -
2812 @item Source_Dirs @tab list @tab - @tab -
2813 @item Source_List_File @tab string @tab - @tab -
2814 @item Locally_Removed_Files @tab list @tab - @tab -
2815 @item Excluded_Source_Files @tab list @tab - @tab -
2816 @item Object_Dir @tab string @tab - @tab -
2817 @item Exec_Dir @tab string @tab - @tab -
2818 @item Excluded_Source_Dirs @tab list @tab - @tab -
2819 @item Excluded_Source_Files @tab list @tab - @tab -
2820 @item Excluded_Source_List_File @tab list @tab - @tab -
2821 @item Inherit_Source_Path @tab list @tab - @tab insensitive
2822 @item Languages @tab list @tab - @tab -
2823 @item Main @tab list @tab - @tab -
2824 @item Main_Language @tab string @tab - @tab -
2825 @item Externally_Built @tab string @tab - @tab -
2826 @item Roots @tab list @tab - @tab file
2828 Library-related attributes @tab @tab @tab @pxref{Library Projects}
2829 @item Library_Dir @tab string @tab - @tab -
2830 @item Library_Name @tab string @tab - @tab -
2831 @item Library_Kind @tab string @tab - @tab -
2832 @item Library_Version @tab string @tab - @tab -
2833 @item Library_Interface @tab string @tab - @tab -
2834 @item Library_Auto_Init @tab string @tab - @tab -
2835 @item Library_Options @tab list @tab - @tab -
2836 @item Leading_Library_Options @tab list @tab - @tab -
2837 @item Library_Src_Dir @tab string @tab - @tab -
2838 @item Library_ALI_Dir @tab string @tab - @tab -
2839 @item Library_GCC @tab string @tab - @tab -
2840 @item Library_Symbol_File @tab string @tab - @tab -
2841 @item Library_Symbol_Policy @tab string @tab - @tab -
2842 @item Library_Reference_Symbol_File @tab string @tab - @tab -
2843 @item Interfaces @tab list @tab - @tab -
2845 Naming @tab @tab @tab @pxref{Naming Schemes}
2846 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
2847 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
2848 @item Separate_Suffix @tab string @tab Naming @tab -
2849 @item Casing @tab string @tab Naming @tab -
2850 @item Dot_Replacement @tab string @tab Naming @tab -
2851 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
2852 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
2853 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
2854 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
2856 Building @tab @tab @tab @pxref{Switches and Project Files}
2857 @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)
2858 @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)
2859 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
2860 @item Local_Config_File @tab string @tab insensitive @tab -
2861 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
2862 @item Global_Compilation_Switches @tab list @tab Builder @tab language
2863 @item Executable @tab string @tab Builder @tab [file]
2864 @item Executable_Suffix @tab string @tab Builder @tab -
2865 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
2867 IDE (used and created by GPS) @tab @tab @tab
2868 @item Remote_Host @tab string @tab IDE @tab -
2869 @item Program_Host @tab string @tab IDE @tab -
2870 @item Communication_Protocol @tab string @tab IDE @tab -
2871 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
2872 @item Debugger_Command @tab string @tab IDE @tab -
2873 @item Gnatlist @tab string @tab IDE @tab -
2874 @item VCS_Kind @tab string @tab IDE @tab -
2875 @item VCS_File_Check @tab string @tab IDE @tab -
2876 @item VCS_Log_Check @tab string @tab IDE @tab -
2877 @item Documentation_Dir @tab string @tab IDE @tab -
2879 Configuration files @tab @tab @tab See gprbuild manual
2880 @item Default_Language @tab string @tab - @tab -
2881 @item Run_Path_Option @tab list @tab - @tab -
2882 @item Run_Path_Origin @tab string @tab - @tab -
2883 @item Separate_Run_Path_Options @tab string @tab - @tab -
2884 @item Toolchain_Version @tab string @tab - @tab insensitive
2885 @item Toolchain_Description @tab string @tab - @tab insensitive
2886 @item Object_Generated @tab string @tab - @tab insensitive
2887 @item Objects_Linked @tab string @tab - @tab insensitive
2888 @item Target @tab string @tab - @tab -
2889 @item Library_Builder @tab string @tab - @tab -
2890 @item Library_Support @tab string @tab - @tab -
2891 @item Archive_Builder @tab list @tab - @tab -
2892 @item Archive_Builder_Append_Option @tab list @tab - @tab -
2893 @item Archive_Indexer @tab list @tab - @tab -
2894 @item Archive_Suffix @tab string @tab - @tab -
2895 @item Library_Partial_Linker @tab list @tab - @tab -
2896 @item Shared_Library_Prefix @tab string @tab - @tab -
2897 @item Shared_Library_Suffix @tab string @tab - @tab -
2898 @item Symbolic_Link_Supported @tab string @tab - @tab -
2899 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
2900 @item Library_Auto_Init_Supported @tab string @tab - @tab -
2901 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
2902 @item Library_Version_Switches @tab list @tab - @tab -
2903 @item Library_Install_Name_Option @tab string @tab - @tab -
2904 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
2905 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
2906 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
2907 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
2908 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
2909 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
2910 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
2911 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
2912 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
2913 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
2914 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
2915 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitve (language)
2916 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
2917 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
2918 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
2919 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
2920 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
2921 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
2922 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
2923 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
2924 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
2925 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
2926 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
2927 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
2928 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
2929 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
2930 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
2931 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
2932 @item Prefix @tab string @tab Binder @tab insensitive (language)
2933 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
2934 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
2935 @item Linker_Options @tab list @tab Linker @tab -
2936 @item Leading_Switches @tab list @tab Linker @tab -
2937 @item Map_File_Options @tab string @tab Linker @tab -
2938 @item Executable_Switches @tab list @tab Linker @tab -
2939 @item Lib_Dir_Switch @tab string @tab Linker @tab -
2940 @item Lib_Name_Switch @tab string @tab Linker @tab -
2941 @item Max_Command_Line_Length @tab string @tab Linker @tab -
2942 @item Response_File_Format @tab string @tab Linker @tab -
2943 @item Response_File_Switches @tab list @tab Linker @tab -
2946 @c ---------------------------------------------
2947 @node Case Statements
2948 @subsection Case Statements
2949 @c ---------------------------------------------
2952 A @b{case} statement is used in a project file to effect conditional
2953 behavior. Through this statement, you can set the value of attributes
2954 and variables depending on the value previously assigned to a typed
2957 All choices in a choice list must be distinct. Unlike Ada, the choice
2958 lists of all alternatives do not need to include all values of the type.
2959 An @code{others} choice must appear last in the list of alternatives.
2961 The syntax of a @code{case} construction is based on the Ada case statement
2962 (although the @code{null} statement for empty alternatives is optional).
2964 The case expression must be a typed string variable, whose value is often
2965 given by an external reference (@pxref{External Values}).
2967 Each alternative starts with the reserved word @code{when}, either a list of
2968 literal strings separated by the @code{"|"} character or the reserved word
2969 @code{others}, and the @code{"=>"} token.
2970 Each literal string must belong to the string type that is the type of the
2972 After each @code{=>}, there are zero or more statements. The only
2973 statements allowed in a case construction are other case statements,
2974 attribute declarations and variable declarations. String type declarations and
2975 package declarations are not allowed. Variable declarations are restricted to
2976 variables that have already been declared before the case construction.
2980 @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
2983 @i{when} discrete_choice_list =>
2985 | attribute_declaration
2986 | variable_declaration
2987 | empty_declaration@}
2989 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
2993 Here is a typical example:
2995 @smallexample @c projectfile
2998 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
2999 OS : OS_Type := external ("OS", "GNU/Linux");
3003 when "GNU/Linux" | "Unix" =>
3004 for Switches ("Ada") use ("-gnath");
3006 for Switches ("Ada") use ("-gnatP");
3015 @c ---------------------------------------------
3016 @node Tools Supporting Project Files
3017 @chapter Tools Supporting Project Files
3018 @c ---------------------------------------------
3024 * gnatmake and Project Files::
3025 * The GNAT Driver and Project Files::
3026 * The Development Environments::
3027 * Cleaning up with GPRclean::
3030 @c ---------------------------------------------
3031 @node gnatmake and Project Files
3032 @section gnatmake and Project Files
3033 @c ---------------------------------------------
3036 This section covers several topics related to @command{gnatmake} and
3037 project files: defining ^switches^switches^ for @command{gnatmake}
3038 and for the tools that it invokes; specifying configuration pragmas;
3039 the use of the @code{Main} attribute; building and rebuilding library project
3043 * Switches Related to Project Files::
3044 * Switches and Project Files::
3045 * Specifying Configuration Pragmas::
3046 * Project Files and Main Subprograms::
3047 * Library Project Files::
3050 @c ---------------------------------------------
3051 @node Switches Related to Project Files
3052 @subsection Switches Related to Project Files
3053 @c ---------------------------------------------
3056 The following switches are used by GNAT tools that support project files:
3060 @item ^-P^/PROJECT_FILE=^@var{project}
3061 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
3062 Indicates the name of a project file. This project file will be parsed with
3063 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
3064 if any, and using the external references indicated
3065 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
3067 There may zero, one or more spaces between @option{-P} and @var{project}.
3070 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3072 Since the Project Manager parses the project file only after all the switches
3073 on the command line are checked, the order of the switches
3074 @option{^-P^/PROJECT_FILE^},
3075 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3076 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3078 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3079 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3080 Indicates that external variable @var{name} has the value @var{value}.
3081 The Project Manager will use this value for occurrences of
3082 @code{external(name)} when parsing the project file.
3085 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3093 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3094 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3095 @var{name}, only the last one is used.
3097 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3098 takes precedence over the value of the same name in the environment.
3100 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3101 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3102 Indicates the verbosity of the parsing of GNAT project files.
3105 @option{-vP0} means Default;
3106 @option{-vP1} means Medium;
3107 @option{-vP2} means High.
3111 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3115 The default is ^Default^DEFAULT^: no output for syntactically correct
3117 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3118 only the last one is used.
3120 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3121 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3122 Add directory <dir> at the beginning of the project search path, in order,
3123 after the current working directory.
3127 @cindex @option{-eL} (any project-aware tool)
3128 Follow all symbolic links when processing project files.
3131 @item ^--subdirs^/SUBDIRS^=<subdir>
3132 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3133 This switch is recognized by gnatmake and gnatclean. It indicate that the real
3134 directories (except the source directories) are the subdirectories <subdir>
3135 of the directories specified in the project files. This applies in particular
3136 to object directories, library directories and exec directories. If the
3137 subdirectories do not exist, they are created automatically.
3141 @c ---------------------------------------------
3142 @node Switches and Project Files
3143 @subsection Switches and Project Files
3144 @c ---------------------------------------------
3148 It is not currently possible to specify VMS style qualifiers in the project
3149 files; only Unix style ^switches^switches^ may be specified.
3152 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3153 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3154 attribute, a @code{Switches} attribute, or both;
3155 as their names imply, these ^switch^switch^-related
3156 attributes affect the ^switches^switches^ that are used for each of these GNAT
3158 @command{gnatmake} is invoked. As will be explained below, these
3159 component-specific ^switches^switches^ precede
3160 the ^switches^switches^ provided on the @command{gnatmake} command line.
3162 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3163 indexed by language name (case insensitive) whose value is a string list.
3166 @smallexample @c projectfile
3169 for ^Default_Switches^Default_Switches^ ("Ada")
3170 use ("^-gnaty^-gnaty^",
3177 The @code{Switches} attribute is indexed on a file name (which may or may
3178 not be case sensitive, depending
3179 on the operating system) whose value is a string list. For example:
3181 @smallexample @c projectfile
3184 for Switches ("main1.adb")
3186 for Switches ("main2.adb")
3193 For the @code{Builder} package, the file names must designate source files
3194 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
3195 file names must designate @file{ALI} or source files for main subprograms.
3196 In each case just the file name without an explicit extension is acceptable.
3198 For each tool used in a program build (@command{gnatmake}, the compiler, the
3199 binder, and the linker), the corresponding package @dfn{contributes} a set of
3200 ^switches^switches^ for each file on which the tool is invoked, based on the
3201 ^switch^switch^-related attributes defined in the package.
3202 In particular, the ^switches^switches^
3203 that each of these packages contributes for a given file @var{f} comprise:
3206 @item the value of attribute @code{Switches (@var{f})},
3207 if it is specified in the package for the given file,
3208 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
3209 if it is specified in the package.
3214 If neither of these attributes is defined in the package, then the package does
3215 not contribute any ^switches^switches^ for the given file.
3217 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
3218 two sets, in the following order: those contributed for the file
3219 by the @code{Builder} package;
3220 and the switches passed on the command line.
3222 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
3223 the ^switches^switches^ passed to the tool comprise three sets,
3224 in the following order:
3228 the applicable ^switches^switches^ contributed for the file
3229 by the @code{Builder} package in the project file supplied on the command line;
3232 those contributed for the file by the package (in the relevant project file --
3233 see below) corresponding to the tool; and
3236 the applicable switches passed on the command line.
3239 The term @emph{applicable ^switches^switches^} reflects the fact that
3240 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
3241 tools, depending on the individual ^switch^switch^.
3243 @command{gnatmake} may invoke the compiler on source files from different
3244 projects. The Project Manager will use the appropriate project file to
3245 determine the @code{Compiler} package for each source file being compiled.
3246 Likewise for the @code{Binder} and @code{Linker} packages.
3248 As an example, consider the following package in a project file:
3250 @smallexample @c projectfile
3254 for ^Default_Switches^Default_Switches^ ("Ada")
3256 for Switches ("a.adb")
3258 for Switches ("b.adb")
3267 If @command{gnatmake} is invoked with this project file, and it needs to
3268 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
3269 @file{a.adb} will be compiled with the ^switch^switch^
3271 @file{b.adb} with ^switches^switches^
3273 and @option{^-gnaty^-gnaty^},
3274 and @file{c.adb} with @option{^-g^-g^}.
3276 The following example illustrates the ordering of the ^switches^switches^
3277 contributed by different packages:
3279 @smallexample @c projectfile
3283 for Switches ("main.adb")
3292 for Switches ("main.adb")
3300 If you issue the command:
3303 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
3307 then the compiler will be invoked on @file{main.adb} with the following
3308 sequence of ^switches^switches^
3311 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
3315 with the last @option{^-O^-O^}
3316 ^switch^switch^ having precedence over the earlier ones;
3317 several other ^switches^switches^
3318 (such as @option{^-c^-c^}) are added implicitly.
3320 The ^switches^switches^
3322 and @option{^-O1^-O1^} are contributed by package
3323 @code{Builder}, @option{^-O2^-O2^} is contributed
3324 by the package @code{Compiler}
3325 and @option{^-O0^-O0^} comes from the command line.
3327 The @option{^-g^-g^}
3328 ^switch^switch^ will also be passed in the invocation of
3331 A final example illustrates switch contributions from packages in different
3334 @smallexample @c projectfile
3337 for Source_Files use ("pack.ads", "pack.adb");
3339 for ^Default_Switches^Default_Switches^ ("Ada")
3340 use ("^-gnata^-gnata^");
3348 for Source_Files use ("foo_main.adb", "bar_main.adb");
3350 for Switches ("foo_main.adb")
3360 procedure Foo_Main is
3369 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
3373 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
3374 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
3375 @option{^-gnato^-gnato^} (passed on the command line).
3376 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
3377 are @option{^-g^-g^} from @code{Proj4.Builder},
3378 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
3379 and @option{^-gnato^-gnato^} from the command line.
3381 When using @command{gnatmake} with project files, some ^switches^switches^ or
3382 arguments may be expressed as relative paths. As the working directory where
3383 compilation occurs may change, these relative paths are converted to absolute
3384 paths. For the ^switches^switches^ found in a project file, the relative paths
3385 are relative to the project file directory, for the switches on the command
3386 line, they are relative to the directory where @command{gnatmake} is invoked.
3387 The ^switches^switches^ for which this occurs are:
3393 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
3395 ^-o^-o^, object files specified in package @code{Linker} or after
3396 -largs on the command line). The exception to this rule is the ^switch^switch^
3397 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
3399 @c ---------------------------------------------
3400 @node Specifying Configuration Pragmas
3401 @subsection Specifying Configuration Pragmas
3402 @c ---------------------------------------------
3405 When using @command{gnatmake} with project files, if there exists a file
3406 @file{gnat.adc} that contains configuration pragmas, this file will be
3409 Configuration pragmas can be defined by means of the following attributes in
3410 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
3411 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
3413 Both these attributes are single string attributes. Their values is the path
3414 name of a file containing configuration pragmas. If a path name is relative,
3415 then it is relative to the project directory of the project file where the
3416 attribute is defined.
3418 When compiling a source, the configuration pragmas used are, in order,
3419 those listed in the file designated by attribute
3420 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
3421 project file, if it is specified, and those listed in the file designated by
3422 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
3423 the project file of the source, if it exists.
3425 @c ---------------------------------------------
3426 @node Project Files and Main Subprograms
3427 @subsection Project Files and Main Subprograms
3428 @c ---------------------------------------------
3431 When using a project file, you can invoke @command{gnatmake}
3432 with one or several main subprograms, by specifying their source files on the
3436 gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
3440 Each of these needs to be a source file of the same project, except
3441 when the switch ^-u^/UNIQUE^ is used.
3443 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
3444 same project, one of the project in the tree rooted at the project specified
3445 on the command line. The package @code{Builder} of this common project, the
3446 "main project" is the one that is considered by @command{gnatmake}.
3448 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
3449 imported directly or indirectly by the project specified on the command line.
3450 Note that if such a source file is not part of the project specified on the
3451 command line, the ^switches^switches^ found in package @code{Builder} of the
3452 project specified on the command line, if any, that are transmitted
3453 to the compiler will still be used, not those found in the project file of
3456 When using a project file, you can also invoke @command{gnatmake} without
3457 explicitly specifying any main, and the effect depends on whether you have
3458 defined the @code{Main} attribute. This attribute has a string list value,
3459 where each element in the list is the name of a source file (the file
3460 extension is optional) that contains a unit that can be a main subprogram.
3462 If the @code{Main} attribute is defined in a project file as a non-empty
3463 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
3464 line, then invoking @command{gnatmake} with this project file but without any
3465 main on the command line is equivalent to invoking @command{gnatmake} with all
3466 the file names in the @code{Main} attribute on the command line.
3469 @smallexample @c projectfile
3472 for Main use ("main1", "main2", "main3");
3478 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
3480 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
3482 When the project attribute @code{Main} is not specified, or is specified
3483 as an empty string list, or when the switch @option{-u} is used on the command
3484 line, then invoking @command{gnatmake} with no main on the command line will
3485 result in all immediate sources of the project file being checked, and
3486 potentially recompiled. Depending on the presence of the switch @option{-u},
3487 sources from other project files on which the immediate sources of the main
3488 project file depend are also checked and potentially recompiled. In other
3489 words, the @option{-u} switch is applied to all of the immediate sources of the
3492 When no main is specified on the command line and attribute @code{Main} exists
3493 and includes several mains, or when several mains are specified on the
3494 command line, the default ^switches^switches^ in package @code{Builder} will
3495 be used for all mains, even if there are specific ^switches^switches^
3496 specified for one or several mains.
3498 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
3499 the specific ^switches^switches^ for each main, if they are specified.
3501 @c ---------------------------------------------
3502 @node Library Project Files
3503 @subsection Library Project Files
3504 @c ---------------------------------------------
3507 When @command{gnatmake} is invoked with a main project file that is a library
3508 project file, it is not allowed to specify one or more mains on the command
3511 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
3512 ^-l^/ACTION=LINK^ have special meanings.
3515 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
3516 to @command{gnatmake} that @command{gnatbind} should be invoked for the
3519 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
3520 to @command{gnatmake} that the binder generated file should be compiled
3521 (in the case of a stand-alone library) and that the library should be built.
3525 @c ---------------------------------------------
3526 @node The GNAT Driver and Project Files
3527 @section The GNAT Driver and Project Files
3528 @c ---------------------------------------------
3531 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
3532 can benefit from project files:
3533 (@command{^gnatbind^gnatbind^},
3534 @command{^gnatcheck^gnatcheck^},
3535 @command{^gnatclean^gnatclean^},
3536 @command{^gnatelim^gnatelim^},
3537 @command{^gnatfind^gnatfind^},
3538 @command{^gnatlink^gnatlink^},
3539 @command{^gnatls^gnatls^},
3540 @command{^gnatmetric^gnatmetric^},
3541 @command{^gnatpp^gnatpp^},
3542 @command{^gnatstub^gnatstub^},
3543 and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
3544 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
3545 They must be invoked through the @command{gnat} driver.
3547 The @command{gnat} driver is a wrapper that accepts a number of commands and
3548 calls the corresponding tool. It was designed initially for VMS platforms (to
3549 convert VMS qualifiers to Unix-style switches), but it is now available on all
3552 On non-VMS platforms, the @command{gnat} driver accepts the following commands
3556 @item BIND to invoke @command{^gnatbind^gnatbind^}
3557 @item CHOP to invoke @command{^gnatchop^gnatchop^}
3558 @item CLEAN to invoke @command{^gnatclean^gnatclean^}
3559 @item COMP or COMPILE to invoke the compiler
3560 @item ELIM to invoke @command{^gnatelim^gnatelim^}
3561 @item FIND to invoke @command{^gnatfind^gnatfind^}
3562 @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
3563 @item LINK to invoke @command{^gnatlink^gnatlink^}
3564 @item LS or LIST to invoke @command{^gnatls^gnatls^}
3565 @item MAKE to invoke @command{^gnatmake^gnatmake^}
3566 @item NAME to invoke @command{^gnatname^gnatname^}
3567 @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
3568 @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
3569 @item METRIC to invoke @command{^gnatmetric^gnatmetric^}
3570 @item STUB to invoke @command{^gnatstub^gnatstub^}
3571 @item XREF to invoke @command{^gnatxref^gnatxref^}
3576 (note that the compiler is invoked using the command
3577 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
3579 On non-VMS platforms, between @command{gnat} and the command, two
3580 special switches may be used:
3583 @item @command{-v} to display the invocation of the tool.
3584 @item @command{-dn} to prevent the @command{gnat} driver from removing
3585 the temporary files it has created. These temporary files are
3586 configuration files and temporary file list files.
3591 The command may be followed by switches and arguments for the invoked
3595 gnat bind -C main.ali
3601 Switches may also be put in text files, one switch per line, and the text
3602 files may be specified with their path name preceded by '@@'.
3605 gnat bind @@args.txt main.ali
3609 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
3610 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
3611 (@option{^-P^/PROJECT_FILE^},
3612 @option{^-X^/EXTERNAL_REFERENCE^} and
3613 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
3614 the switches of the invoking tool.
3616 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
3617 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
3618 the immediate sources of the specified project file.
3620 When GNAT METRIC is used with a project file, but with no source
3621 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
3622 with all the immediate sources of the specified project file and with
3623 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
3626 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
3627 a project file, no source is specified on the command line and
3628 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
3629 the underlying tool (^gnatpp^gnatpp^ or
3630 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
3631 not only for the immediate sources of the main project.
3633 (-U stands for Universal or Union of the project files of the project tree)
3636 For each of the following commands, there is optionally a corresponding
3637 package in the main project.
3640 @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
3642 @item package @code{Check} for command CHECK (invoking
3643 @code{^gnatcheck^gnatcheck^})
3645 @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
3647 @item package @code{Cross_Reference} for command XREF (invoking
3648 @code{^gnatxref^gnatxref^})
3650 @item package @code{Eliminate} for command ELIM (invoking
3651 @code{^gnatelim^gnatelim^})
3653 @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
3655 @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
3657 @item package @code{Gnatstub} for command STUB
3658 (invoking @code{^gnatstub^gnatstub^})
3660 @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
3662 @item package @code{Check} for command CHECK
3663 (invoking @code{^gnatcheck^gnatcheck^})
3665 @item package @code{Metrics} for command METRIC
3666 (invoking @code{^gnatmetric^gnatmetric^})
3668 @item package @code{Pretty_Printer} for command PP or PRETTY
3669 (invoking @code{^gnatpp^gnatpp^})
3674 Package @code{Gnatls} has a unique attribute @code{Switches},
3675 a simple variable with a string list value. It contains ^switches^switches^
3676 for the invocation of @code{^gnatls^gnatls^}.
3678 @smallexample @c projectfile
3691 All other packages have two attribute @code{Switches} and
3692 @code{^Default_Switches^Default_Switches^}.
3694 @code{Switches} is an indexed attribute, indexed by the
3695 source file name, that has a string list value: the ^switches^switches^ to be
3696 used when the tool corresponding to the package is invoked for the specific
3699 @code{^Default_Switches^Default_Switches^} is an attribute,
3700 indexed by the programming language that has a string list value.
3701 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
3702 ^switches^switches^ for the invocation of the tool corresponding
3703 to the package, except if a specific @code{Switches} attribute
3704 is specified for the source file.
3706 @smallexample @c projectfile
3710 for Source_Dirs use ("./**");
3721 for ^Default_Switches^Default_Switches^ ("Ada")
3722 use ("^-gnatv^-gnatv^",
3723 "^-gnatwa^-gnatwa^");
3729 for ^Default_Switches^Default_Switches^ ("Ada")
3737 for ^Default_Switches^Default_Switches^ ("Ada")
3739 for Switches ("main.adb")
3748 for ^Default_Switches^Default_Switches^ ("Ada")
3755 package Cross_Reference is
3756 for ^Default_Switches^Default_Switches^ ("Ada")
3761 end Cross_Reference;
3767 With the above project file, commands such as
3770 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
3771 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
3772 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
3773 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
3774 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
3778 will set up the environment properly and invoke the tool with the switches
3779 found in the package corresponding to the tool:
3780 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
3781 except @code{Switches ("main.adb")}
3782 for @code{^gnatlink^gnatlink^}.
3783 It is also possible to invoke some of the tools,
3784 (@code{^gnatcheck^gnatcheck^},
3785 @code{^gnatmetric^gnatmetric^},
3786 and @code{^gnatpp^gnatpp^})
3787 on a set of project units thanks to the combination of the switches
3788 @option{-P}, @option{-U} and possibly the main unit when one is interested
3789 in its closure. For instance,
3795 will compute the metrics for all the immediate units of project
3798 gnat metric -Pproj -U
3802 will compute the metrics for all the units of the closure of projects
3803 rooted at @code{proj}.
3805 gnat metric -Pproj -U main_unit
3809 will compute the metrics for the closure of units rooted at
3810 @code{main_unit}. This last possibility relies implicitly
3811 on @command{gnatbind}'s option @option{-R}. But if the argument files for the
3812 tool invoked by the the @command{gnat} driver are explicitly specified
3813 either directly or through the tool @option{-files} option, then the tool
3814 is called only for these explicitly specified files.
3816 @c ---------------------------------------------
3817 @node The Development Environments
3818 @section The Development Environments
3819 @c ---------------------------------------------
3822 See the appropriate manuals for more details. These environments will
3823 store a number of settings in the project itself, when they are meant
3824 to be shared by the whole team working on the project. Here are the
3825 attributes defined in the package @b{IDE} in projects.
3829 This is a simple attribute. Its value is a string that designates the remote
3830 host in a cross-compilation environment, to be used for remote compilation and
3831 debugging. This field should not be specified when running on the local
3835 This is a simple attribute. Its value is a string that specifies the
3836 name of IP address of the embedded target in a cross-compilation environment,
3837 on which the program should execute.
3839 @item Communication_Protocol
3840 This is a simple string attribute. Its value is the name of the protocol
3841 to use to communicate with the target in a cross-compilation environment,
3842 e.g.@: @code{"wtx"} or @code{"vxworks"}.
3844 @item Compiler_Command
3845 This is an associative array attribute, whose domain is a language name. Its
3846 value is string that denotes the command to be used to invoke the compiler.
3847 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
3848 gnatmake, in particular in the handling of switches.
3850 @item Debugger_Command
3851 This is simple attribute, Its value is a string that specifies the name of
3852 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
3854 @item Default_Switches
3855 This is an associative array attribute. Its indexes are the name of the
3856 external tools that the GNAT Programming System (GPS) is supporting. Its
3857 value is a list of switches to use when invoking that tool.
3860 This is a simple attribute. Its value is a string that specifies the name
3861 of the @command{gnatls} utility to be used to retrieve information about the
3862 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
3864 This is a simple attribute. Its value is a string used to specify the
3865 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
3866 ClearCase or Perforce.
3868 @item VCS_File_Check
3869 This is a simple attribute. Its value is a string that specifies the
3870 command used by the VCS to check the validity of a file, either
3871 when the user explicitly asks for a check, or as a sanity check before
3875 This is a simple attribute. Its value is a string that specifies
3876 the command used by the VCS to check the validity of a log file.
3878 @item VCS_Repository_Root
3879 The VCS repository root path. This is used to create tags or branches
3880 of the repository. For subversion the value should be the @code{URL}
3881 as specified to check-out the working copy of the repository.
3883 @item VCS_Patch_Root
3884 The local root directory to use for building patch file. All patch chunks
3885 will be relative to this path. The root project directory is used if
3886 this value is not defined.
3890 @c ---------------------------------------------
3891 @node Cleaning up with GPRclean
3892 @section Cleaning up with GPRclean
3893 @c ---------------------------------------------
3896 The GPRclean tool removes the files created by GPRbuild.
3897 At a minimum, to invoke GPRclean you must specify a main project file
3898 in a command such as @code{gprclean proj.gpr} or @code{gprclean -P proj.gpr}.
3900 Examples of invocation of GPRclean:
3903 gprclean -r prj1.gpr
3904 gprclean -c -P prj2.gpr
3908 * Switches for GPRclean::
3911 @c ---------------------------------------------
3912 @node Switches for GPRclean
3913 @subsection Switches for GPRclean
3914 @c ---------------------------------------------
3917 The switches for GPRclean are:
3920 @item @option{--config=<main config project file name>} : Specify the
3921 configuration project file name
3923 @item @option{--autoconf=<config project file name>}
3925 This specifies a configuration project file name that already exists or will
3926 be created automatically. Option @option{--autoconf=}
3927 cannot be specified more than once. If the configuration project file
3928 specified with @option{--autoconf=} exists, then it is used. Otherwise,
3929 @value{gprconfig} is invoked to create it automatically.
3931 @item @option{-c} : Only delete compiler-generated files. Do not delete
3932 executables and libraries.
3934 @item @option{-f} : Force deletions of unwritable files
3936 @item @option{-F} : Display full project path name in brief error messages
3938 @item @option{-h} : Display this message
3940 @item @option{-n} : Do not delete files, only list files to delete
3942 @item @option{-P<proj>} : Use Project File @emph{<proj>}.
3944 @item @option{-q} : Be quiet/terse. There is no output, except to report
3947 @item @option{-r} : (recursive) Clean all projects referenced by the main
3948 project directly or indirectly. Without this switch, GPRclean only
3949 cleans the main project.
3951 @item @option{-v} : Verbose mode
3953 @item @option{-vPx} : Specify verbosity when parsing Project Files.
3954 x = 0 (default), 1 or 2.
3956 @item @option{-Xnm=val} : Specify an external reference for Project Files.