10SN/A@set gprconfig GPRconfig 21472SN/A 30SN/A@c ------ projects.texi 40SN/A@c Copyright (C) 2002-2014, Free Software Foundation, Inc. 50SN/A@c This file is shared between the GNAT user's guide and gprbuild. It is not 60SN/A@c compilable on its own, you should instead compile the other two manuals. 70SN/A@c For that reason, there is no toplevel @menu 80SN/A 90SN/A@c --------------------------------------------- 100SN/A@node GNAT Project Manager 110SN/A@chapter GNAT Project Manager 120SN/A@c --------------------------------------------- 130SN/A 140SN/A@noindent 150SN/A@menu 160SN/A* Introduction:: 170SN/A* Building With Projects:: 180SN/A* Organizing Projects into Subsystems:: 191472SN/A* Scenarios in Projects:: 201472SN/A* Library Projects:: 211472SN/A* Project Extension:: 220SN/A* Aggregate Projects:: 230SN/A* Aggregate Library Projects:: 240SN/A* Project File Reference:: 250SN/A@end menu 260SN/A 270SN/A@c --------------------------------------------- 280SN/A@node Introduction 290SN/A@section Introduction 300SN/A@c --------------------------------------------- 310SN/A 320SN/A@noindent 33This chapter describes GNAT's @emph{Project Manager}, a facility that allows 34you to manage complex builds involving a number of source files, directories, 35and options for different system configurations. In particular, 36project files allow you to specify: 37 38@itemize @bullet 39@item The directory or set of directories containing the source files, and/or the 40 names of the specific source files themselves 41@item The directory in which the compiler's output 42 (@file{ALI} files, object files, tree files, etc.) is to be placed 43@item The directory in which the executable programs are to be placed 44@item Switch settings for any of the project-enabled tools; 45 you can apply these settings either globally or to individual compilation units. 46@item The source files containing the main subprogram(s) to be built 47@item The source programming language(s) 48@item Source file naming conventions; you can specify these either globally or for 49 individual compilation units (@pxref{Naming Schemes}). 50@item Change any of the above settings depending on external values, thus enabling 51 the reuse of the projects in various @b{scenarios} (@pxref{Scenarios in Projects}). 52@item Automatically build libraries as part of the build process 53 (@pxref{Library Projects}). 54 55@end itemize 56 57@noindent 58Project files are written in a syntax close to that of Ada, using familiar 59notions such as packages, context clauses, declarations, default values, 60assignments, and inheritance (@pxref{Project File Reference}). 61 62Project files can be built hierarchically from other project files, simplifying 63complex system integration and project reuse (@pxref{Organizing Projects into 64Subsystems}). 65 66@itemize @bullet 67@item One project can import other projects containing needed source files. 68 More generally, the Project Manager lets you structure large development 69 efforts into hierarchical subsystems, where build decisions are delegated 70 to the subsystem level, and thus different compilation environments 71 (switch settings) used for different subsystems. 72@item You can organize GNAT projects in a hierarchy: a child project 73 can extend a parent project, inheriting the parent's source files and 74 optionally overriding any of them with alternative versions 75 (@pxref{Project Extension}). 76 77@end itemize 78 79@noindent 80Several tools support project files, generally in addition to specifying 81the information on the command line itself). They share common switches 82to control the loading of the project (in particular 83@option{-P@emph{projectfile}} and 84@option{-X@emph{vbl}=@emph{value}}). 85 86The Project Manager supports a wide range of development strategies, 87for systems of all sizes. Here are some typical practices that are 88easily handled: 89 90@itemize @bullet 91@item Using a common set of source files and generating object files in different 92 directories via different switch settings. It can be used for instance, for 93 generating separate sets of object files for debugging and for production. 94@item Using a mostly-shared set of source files with different versions of 95 some units or subunits. It can be used for instance, for grouping and hiding 96 all OS dependencies in a small number of implementation units. 97@end itemize 98 99@noindent 100Project files can be used to achieve some of the effects of a source 101versioning system (for example, defining separate projects for 102the different sets of sources that comprise different releases) but the 103Project Manager is independent of any source configuration management tool 104that might be used by the developers. 105 106The various sections below introduce the different concepts related to 107projects. Each section starts with examples and use cases, and then goes into 108the details of related project file capabilities. 109 110@c --------------------------------------------- 111@node Building With Projects 112@section Building With Projects 113@c --------------------------------------------- 114 115@noindent 116In its simplest form, a unique project is used to build a single executable. 117This section concentrates on such a simple setup. Later sections will extend 118this basic model to more complex setups. 119 120The following concepts are the foundation of project files, and will be further 121detailed later in this documentation. They are summarized here as a reference. 122 123@table @asis 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 130 build process. 131 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}. 137 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}. 144 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}. 151 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. 167 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. 176 177@end table 178 179The following subsections introduce gradually all the attributes of interest 180for simple build needs. Here is the simple setup that will be used in the 181following examples. 182 183The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in 184the @file{common/} directory. The file @file{proc.adb} contains an Ada main 185subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile 186these source files with the switch 187@option{-O2}, and put the resulting files in 188the directory @file{obj/}. 189 190@smallexample 191@group 192common/ 193 pack.ads 194 pack.adb 195 proc.adb 196@end group 197@group 198common/obj/ 199 proc.ali, proc.o pack.ali, pack.o 200@end group 201@end smallexample 202 203@noindent 204Our project is to be called @emph{Build}. The name of the 205file is the name of the project (case-insensitive) with the 206@file{.gpr} extension, therefore the project file name is @file{build.gpr}. This 207is not mandatory, but a warning is issued when this convention is not followed. 208 209This is a very simple example, and as stated above, a single project 210file is enough for it. We will thus create a new file, that for now 211should contain the following code: 212 213@smallexample 214@b{project} Build @b{is} 215@b{end} Build; 216@end smallexample 217 218@menu 219* Source Files and Directories:: 220* Duplicate Sources in Projects:: 221* Object and Exec Directory:: 222* Main Subprograms:: 223* Tools Options in Project Files:: 224* Compiling with Project Files:: 225* Executable File Names:: 226* Avoid Duplication With Variables:: 227* Naming Schemes:: 228* Installation:: 229* Distributed support:: 230@end menu 231 232@c --------------------------------------------- 233@node Source Files and Directories 234@subsection Source Files and Directories 235@c --------------------------------------------- 236 237@noindent 238When you create a new project, the first thing to describe is how to find the 239corresponding source files. These are the only settings that are needed by all 240the tools that will use this project (builder, compiler, binder and linker for 241the compilation, IDEs to edit the source files,@dots{}). 242 243@cindex Source directories 244The first step is to declare the source directories, which are the directories 245to be searched to find source files. In the case of the example, 246the @file{common} directory is the only source directory. 247 248@cindex @code{Source_Dirs} 249There are several ways of defining source directories: 250 251@itemize @bullet 252@item When the attribute @b{Source_Dirs} is not used, a project contains a 253 single source directory which is the one where the project file itself 254 resides. In our example, if @file{build.gpr} is placed in the @file{common} 255 directory, the project has the needed implicit source directory. 256 257@item The attribute @b{Source_Dirs} can be set to a list of path names, one 258 for each of the source directories. Such paths can either be absolute 259 names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the 260 directory in which the project file resides (for instance "." if 261 @file{build.gpr} is inside @file{common/}, or "common" if it is one level up). 262 Each of the source directories must exist and be readable. 263 264@cindex portability 265 The syntax for directories is platform specific. For portability, however, 266 the project manager will always properly translate UNIX-like path names to 267 the native format of the specific platform. For instance, when the same 268 project file is to be used both on Unix and Windows, "/" should be used as 269 the directory separator rather than "\". 270 271@item The attribute @b{Source_Dirs} can automatically include subdirectories 272 using a special syntax inspired by some UNIX shells. If any of the paths in 273 the list ends with "@file{**}", then that path and all its subdirectories 274 (recursively) are included in the list of source directories. For instance, 275 @file{**} and @file{./**} represent the complete directory tree rooted at 276 the directory in which the project file resides. 277@cindex Source directories, recursive 278 279@cindex @code{Excluded_Source_Dirs} 280 When using that construct, it can sometimes be convenient to also use the 281 attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry 282 specifies a directory whose immediate content, not including subdirs, is to 283 be excluded. It is also possible to exclude a complete directory subtree 284 using the "**" notation. 285 286@cindex @code{Ignore_Source_Sub_Dirs} 287 It is often desirable to remove, from the source directories, directory 288 subtrees rooted at some subdirectories. An example is the subdirectories 289 created by a Version Control System such as Subversion that creates directory 290 subtrees rooted at subdirectories ".svn". To do that, attribute 291 @b{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple 292 file names for the roots of these undesirable directory subtrees. 293 294@smallexample 295 @b{for} Source_Dirs @b{use} ("./**"); 296 @b{for} Ignore_Source_Sub_Dirs @b{use} (".svn"); 297@end smallexample 298 299@end itemize 300 301@noindent 302When applied to the simple example, and because we generally prefer to have 303the project file at the toplevel directory rather than mixed with the sources, 304we will create the following file 305 306@smallexample 307 build.gpr 308 @b{project} Build @b{is} 309 @b{for} Source_Dirs @b{use} ("common"); -- <<<< 310 @b{end} Build; 311@end smallexample 312 313@noindent 314Once source directories have been specified, one may need to indicate 315source files of interest. By default, all source files present in the source 316directories are considered by the project manager. When this is not desired, 317it is possible to specify the list of sources to consider explicitly. 318In such a case, only source file base names are indicated and not 319their absolute or relative path names. The project manager is in charge of 320locating the specified source files in the specified source directories. 321 322@itemize @bullet 323@item By default, the project manager searches for all source files of all 324 specified languages in all the source directories. 325 326 Since the project manager was initially developed for Ada environments, the 327 default language is usually Ada and the above project file is complete: it 328 defines without ambiguity the sources composing the project: that is to say, 329 all the sources in subdirectory "common" for the default language (Ada) using 330 the default naming convention. 331 332@cindex @code{Languages} 333 However, when compiling a multi-language application, or a pure C 334 application, the project manager must be told which languages are of 335 interest, which is done by setting the @b{Languages} attribute to a list of 336 strings, each of which is the name of a language. Tools like 337 @command{gnatmake} only know about Ada, while other tools like 338 @command{gprbuild} know about many more languages such as C, C++, Fortran, 339 assembly and others can be added dynamically. 340 341@cindex Naming scheme 342 Even when using only Ada, the default naming might not be suitable. Indeed, 343 how does the project manager recognizes an "Ada file" from any other 344 file? Project files can describe the naming scheme used for source files, 345 and override the default (@pxref{Naming Schemes}). The default is the 346 standard GNAT extension (@file{.adb} for bodies and @file{.ads} for 347 specs), which is what is used in our example, explaining why no naming scheme 348 is explicitly specified. 349 @xref{Naming Schemes}. 350 351@item @code{Source_Files} 352@cindex @code{Source_Files} 353 In some cases, source directories might contain files that should not be 354 included in a project. One can specify the explicit list of file names to 355 be considered through the @b{Source_Files} attribute. 356 When this attribute is defined, instead of looking at every file in the 357 source directories, the project manager takes only those names into 358 consideration reports errors if they cannot be found in the source 359 directories or does not correspond to the naming scheme. 360 361@item For various reasons, it is sometimes useful to have a project with no 362 sources (most of the time because the attributes defined in the project 363 file will be reused in other projects, as explained in 364 @pxref{Organizing Projects into Subsystems}. To do this, the attribute 365 @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively, 366 @emph{Source_Dirs} can be set to the empty list, with the same 367 result. 368 369@item @code{Source_List_File} 370@cindex @code{Source_List_File} 371 If there is a great number of files, it might be more convenient to use 372 the attribute @b{Source_List_File}, which specifies the full path of a file. 373 This file must contain a list of source file names (one per line, no 374 directory information) that are searched as if they had been defined 375 through @emph{Source_Files}. Such a file can easily be created through 376 external tools. 377 378 A warning is issued if both attributes @code{Source_Files} and 379 @code{Source_List_File} are given explicit values. In this case, the 380 attribute @code{Source_Files} prevails. 381 382@item @code{Excluded_Source_Files} 383@cindex @code{Excluded_Source_Files} 384@cindex @code{Locally_Removed_Files} 385@cindex @code{Excluded_Source_List_File} 386 Specifying an explicit list of files is not always convenient.It might be 387 more convenient to use the default search rules with specific exceptions. 388 This can be done thanks to the attribute @b{Excluded_Source_Files} 389 (or its synonym @b{Locally_Removed_Files}). 390 Its value is the list of file names that should not be taken into account. 391 This attribute is often used when extending a project, 392 @xref{Project Extension}. A similar attribute 393 @b{Excluded_Source_List_File} plays the same 394 role but takes the name of file containing file names similarly to 395 @code{Source_List_File}. 396 397@end itemize 398 399@noindent 400In most simple cases, such as the above example, the default source file search 401behavior provides the expected result, and we do not need to add anything after 402setting @code{Source_Dirs}. The project manager automatically finds 403@file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the 404project. 405 406Note that by default a warning is issued when a project has no sources attached 407to it and this is not explicitly indicated in the project file. 408 409@c --------------------------------------------- 410@node Duplicate Sources in Projects 411@subsection Duplicate Sources in Projects 412@c --------------------------------------------- 413 414@noindent 415If the order of the source directories is known statically, that is if 416@code{"/**"} is not used in the string list @code{Source_Dirs}, then there may 417be several files with the same name sitting in different directories of the 418project. In this case, only the file in the first directory is considered as a 419source of the project and the others are hidden. If @code{"/**"} is used in the 420string list @code{Source_Dirs}, it is an error to have several files with the 421same name in the same directory @code{"/**"} subtree, since there would be an 422ambiguity as to which one should be used. However, two files with the same name 423may exist in two single directories or directory subtrees. In this case, the 424one in the first directory or directory subtree is a source of the project. 425 426If there are two sources in different directories of the same @code{"/**"} 427subtree, one way to resolve the problem is to exclude the directory of the 428file that should not be used as a source of the project. 429 430@c --------------------------------------------- 431@node Object and Exec Directory 432@subsection Object and Exec Directory 433@c --------------------------------------------- 434 435@noindent 436The next step when writing a project is to indicate where the compiler should 437put the object files. In fact, the compiler and other tools might create 438several different kind of files (for GNAT, there is the object file and the ALI 439file for instance). One of the important concepts in projects is that most 440tools may consider source directories as read-only and do not attempt to create 441new or temporary files there. Instead, all files are created in the object 442directory. It is of course not true for project-aware IDEs, whose purpose it is 443to create the source files. 444 445@cindex @code{Object_Dir} 446The object directory is specified through the @b{Object_Dir} attribute. 447Its value is the path to the object directory, either absolute or 448relative to the directory containing the project file. This 449directory must already exist and be readable and writable, although 450some tools have a switch to create the directory if needed (See 451the switch @code{-p} for @command{gnatmake} 452and @command{gprbuild}). 453 454If the attribute @code{Object_Dir} is not specified, it defaults to 455the project directory, that is the directory containing the project file. 456 457For our example, we can specify the object dir in this way: 458 459@smallexample 460 @b{project} Build @b{is} 461 @b{for} Source_Dirs @b{use} ("common"); 462 @b{for} Object_Dir @b{use} "obj"; -- <<<< 463 @b{end} Build; 464@end smallexample 465 466@noindent 467As mentioned earlier, there is a single object directory per project. As a 468result, if you have an existing system where the object files are spread across 469several directories, you can either move all of them into the same directory if 470you want to build it with a single project file, or study the section on 471subsystems (@pxref{Organizing Projects into Subsystems}) to see how each 472separate object directory can be associated with one of the subsystems 473constituting the application. 474 475When the @command{linker} is called, it usually creates an executable. By 476default, this executable is placed in the object directory of the project. It 477might be convenient to store it in its own directory. 478 479@cindex @code{Exec_Dir} 480This can be done through the @code{Exec_Dir} attribute, which, like 481@emph{Object_Dir} contains a single absolute or relative path and must point to 482an existing and writable directory, unless you ask the tool to create it on 483your behalf. When not specified, It defaults to the object directory and 484therefore to the project file's directory if neither @emph{Object_Dir} nor 485@emph{Exec_Dir} was specified. 486 487In the case of the example, let's place the executable in the root 488of the hierarchy, ie the same directory as @file{build.gpr}. Hence 489the project file is now 490 491@smallexample 492 @b{project} Build @b{is} 493 @b{for} Source_Dirs @b{use} ("common"); 494 @b{for} Object_Dir @b{use} "obj"; 495 @b{for} Exec_Dir @b{use} "."; -- <<<< 496 @b{end} Build; 497@end smallexample 498 499@c --------------------------------------------- 500@node Main Subprograms 501@subsection Main Subprograms 502@c --------------------------------------------- 503 504@noindent 505In the previous section, executables were mentioned. The project manager needs 506to be taught what they are. In a project file, an executable is indicated by 507pointing to the source file of a main subprogram. In C this is the file that 508contains the @code{main} function, and in Ada the file that contains the main 509unit. 510 511There can be any number of such main files within a given project, and thus 512several executables can be built in the context of a single project file. Of 513course, one given executable might not (and in fact will not) need all the 514source files referenced by the project. As opposed to other build environments 515such as @command{makefile}, one does not need to specify the list of 516dependencies of each executable, the project-aware builder knows enough of the 517semantics of the languages to build and link only the necessary elements. 518 519@cindex @code{Main} 520The list of main files is specified via the @b{Main} attribute. It contains 521a list of file names (no directories). If a project defines this 522attribute, it is not necessary to identify main files on the 523command line when invoking a builder, and editors like 524@command{GPS} will be able to create extra menus to spawn or debug the 525corresponding executables. 526 527@smallexample 528 @b{project} Build @b{is} 529 @b{for} Source_Dirs @b{use} ("common"); 530 @b{for} Object_Dir @b{use} "obj"; 531 @b{for} Exec_Dir @b{use} "."; 532 @b{for} Main @b{use} ("proc.adb"); -- <<<< 533 @b{end} Build; 534@end smallexample 535 536@noindent 537If this attribute is defined in the project, then spawning the builder 538with a command such as 539 540@smallexample 541 gprbuild -Pbuild 542@end smallexample 543 544@noindent 545automatically builds all the executables corresponding to the files 546listed in the @emph{Main} attribute. It is possible to specify one 547or more executables on the command line to build a subset of them. 548 549@c --------------------------------------------- 550@node Tools Options in Project Files 551@subsection Tools Options in Project Files 552@c --------------------------------------------- 553 554@noindent 555We now have a project file that fully describes our environment, and can be 556used to build the application with a simple @command{gprbuild} command as seen 557in the previous section. In fact, the empty project we showed immediately at 558the beginning (with no attribute at all) could already fulfill that need if it 559was put in the @file{common} directory. 560 561Of course, we might want more control. This section shows you how to specify 562the compilation switches that the various tools involved in the building of the 563executable should use. 564 565@cindex command line length 566Since source names and locations are described in the project file, it is not 567necessary to use switches on the command line for this purpose (switches such 568as -I for gcc). This removes a major source of command line length overflow. 569Clearly, the builders will have to communicate this information one way or 570another to the underlying compilers and tools they call but they usually use 571response files for this and thus are not subject to command line overflows. 572 573Several tools participate to the creation of an executable: the compiler 574produces object files from the source files; the binder (in the Ada case) 575creates a "source" file that takes care, among other things, of elaboration 576issues and global variable initialization; and the linker gathers everything 577into a single executable that users can execute. All these tools are known to 578the project manager and will be called with user defined switches from the 579project files. However, we need to introduce a new project file concept to 580express the switches to be used for any of the tools involved in the build. 581 582@cindex project file packages 583A project file is subdivided into zero or more @b{packages}, each of which 584contains the attributes specific to one tool (or one set of tools). Project 585files use an Ada-like syntax for packages. Package names permitted in project 586files are restricted to a predefined set (@pxref{Packages}), and the contents 587of packages are limited to a small set of constructs and attributes 588(@pxref{Attributes}). 589 590Our example project file can be extended with the following empty packages. At 591this stage, they could all be omitted since they are empty, but they show which 592packages would be involved in the build process. 593 594@smallexample 595 @b{project} Build @b{is} 596 @b{for} Source_Dirs @b{use} ("common"); 597 @b{for} Object_Dir @b{use} "obj"; 598 @b{for} Exec_Dir @b{use} "."; 599 @b{for} Main @b{use} ("proc.adb"); 600 601 @b{package} Builder @b{is} --<<< for gnatmake and gprbuild 602 @b{end} Builder; 603 604 @b{package} Compiler @b{is} --<<< for the compiler 605 @b{end} Compiler; 606 607 @b{package} Binder @b{is} --<<< for the binder 608 @b{end} Binder; 609 610 @b{package} Linker @b{is} --<<< for the linker 611 @b{end} Linker; 612 @b{end} Build; 613@end smallexample 614 615@noindent 616Let's first examine the compiler switches. As stated in the initial description 617of the example, we want to compile all files with @option{-O2}. This is a 618compiler switch, although it is usual, on the command line, to pass it to the 619builder which then passes it to the compiler. It is recommended to use directly 620the right package, which will make the setup easier to understand for other 621people. 622 623Several attributes can be used to specify the switches: 624 625@table @asis 626@item @b{Default_Switches}: 627@cindex @code{Default_Switches} 628 This is the first mention in this manual of an @b{indexed attribute}. When 629 this attribute is defined, one must supply an @emph{index} in the form of a 630 literal string. 631 In the case of @emph{Default_Switches}, the index is the name of the 632 language to which the switches apply (since a different compiler will 633 likely be used for each language, and each compiler has its own set of 634 switches). The value of the attribute is a list of switches. 635 636 In this example, we want to compile all Ada source files with the switch 637 @option{-O2}, and the resulting project file is as follows 638 (only the @code{Compiler} package is shown): 639 640 @smallexample 641 @b{package} Compiler @b{is} 642 @b{for} Default_Switches ("Ada") @b{use} ("-O2"); 643 @b{end} Compiler; 644 @end smallexample 645 646@item @b{Switches}: 647@cindex @code{Switches} 648 in some cases, we might want to use specific switches 649 for one or more files. For instance, compiling @file{proc.adb} might not be 650 possible at high level of optimization because of a compiler issue. 651 In such a case, the @emph{Switches} 652 attribute (indexed on the file name) can be used and will override the 653 switches defined by @emph{Default_Switches}. Our project file would 654 become: 655 656 @smallexample 657 package Compiler is 658 for Default_Switches ("Ada") 659 use ("-O2"); 660 for Switches ("proc.adb") 661 use ("-O0"); 662 end Compiler; 663 @end smallexample 664 665 @noindent 666 @code{Switches} may take a pattern as an index, such as in: 667 668 @smallexample 669 package Compiler is 670 for Default_Switches ("Ada") 671 use ("-O2"); 672 for Switches ("pkg*") 673 use ("-O0"); 674 end Compiler; 675 @end smallexample 676 677 @noindent 678 Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0, 679 not -O2. 680 681 @noindent 682 @code{Switches} can also be given a language name as index instead of a file 683 name in which case it has the same semantics as @emph{Default_Switches}. 684 However, indexes with wild cards are never valid for language name. 685 686@item @b{Local_Configuration_Pragmas}: 687@cindex @code{Local_Configuration_Pragmas} 688 this attribute may specify the path 689 of a file containing configuration pragmas for use by the Ada compiler, 690 such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be 691 used for all the sources of the project. 692 693@end table 694 695The switches for the other tools are defined in a similar manner through the 696@b{Default_Switches} and @b{Switches} attributes, respectively in the 697@emph{Builder} package (for @command{gnatmake} and @command{gprbuild}), 698the @emph{Binder} package (binding Ada executables) and the @emph{Linker} 699package (for linking executables). 700 701@c --------------------------------------------- 702@node Compiling with Project Files 703@subsection Compiling with Project Files 704@c --------------------------------------------- 705 706@noindent 707Now that our project files are written, let's build our executable. 708Here is the command we would use from the command line: 709 710@smallexample 711 gnatmake -Pbuild 712@end smallexample 713 714@noindent 715This will automatically build the executables specified through the 716@emph{Main} attribute: for each, it will compile or recompile the 717sources for which the object file does not exist or is not up-to-date; it 718will then run the binder; and finally run the linker to create the 719executable itself. 720 721@command{gnatmake} only knows how to handle Ada files. By using 722@command{gprbuild} as a builder, you could automatically manage C files the 723same way: create the file @file{utils.c} in the @file{common} directory, 724set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run 725 726@smallexample 727 gprbuild -Pbuild 728@end smallexample 729 730@noindent 731Gprbuild knows how to recompile the C files and will 732recompile them only if one of their dependencies has changed. No direct 733indication on how to build the various elements is given in the 734project file, which describes the project properties rather than a 735set of actions to be executed. Here is the invocation of 736@command{gprbuild} when building a multi-language program: 737 738@smallexample 739$ gprbuild -Pbuild 740gcc -c proc.adb 741gcc -c pack.adb 742gcc -c utils.c 743gprbind proc 744... 745gcc proc.o -o proc 746@end smallexample 747 748@noindent 749Notice the three steps described earlier: 750 751@itemize @bullet 752@item The first three gcc commands correspond to the compilation phase. 753@item The gprbind command corresponds to the post-compilation phase. 754@item The last gcc command corresponds to the final link. 755 756@end itemize 757 758@noindent 759@cindex @option{-v} option (for GPRbuild) 760The default output of GPRbuild's execution is kept reasonably simple and easy 761to understand. In particular, some of the less frequently used commands are not 762shown, and some parameters are abbreviated. So it is not possible to rerun the 763effect of the @command{gprbuild} command by cut-and-pasting its output. 764GPRbuild's option @code{-v} provides a much more verbose output which includes, 765among other information, more complete compilation, post-compilation and link 766commands. 767 768@c --------------------------------------------- 769@node Executable File Names 770@subsection Executable File Names 771@c --------------------------------------------- 772 773@noindent 774@cindex @code{Executable} 775By default, the executable name corresponding to a main file is 776computed from the main source file name. Through the attribute 777@b{Builder.Executable}, it is possible to change this default. 778 779For instance, instead of building @command{proc} (or @command{proc.exe} 780on Windows), we could configure our project file to build "proc1" 781(resp proc1.exe) with the following addition: 782 783@smallexample @c projectfile 784 @b{project} Build @b{is} 785 ... --@i{ same as before} 786 @b{package} Builder @b{is} 787 @b{for} Executable ("proc.adb") @b{use} "proc1"; 788 @b{end} Builder 789 @b{end} Build; 790@end smallexample 791 792@noindent 793@cindex @code{Executable_Suffix} 794Attribute @b{Executable_Suffix}, when specified, may change the suffix 795of the executable files, when no attribute @code{Executable} applies: 796its value replaces the platform-specific executable suffix. 797The default executable suffix is empty on UNIX and ".exe" on Windows. 798 799It is also possible to change the name of the produced executable by using the 800command line switch @option{-o}. When several mains are defined in the project, 801it is not possible to use the @option{-o} switch and the only way to change the 802names of the executable is provided by Attributes @code{Executable} and 803@code{Executable_Suffix}. 804 805@c --------------------------------------------- 806@node Avoid Duplication With Variables 807@subsection Avoid Duplication With Variables 808@c --------------------------------------------- 809 810@noindent 811To illustrate some other project capabilities, here is a slightly more complex 812project using similar sources and a main program in C: 813 814@smallexample @c projectfile 815@b{project} C_Main @b{is} 816 @b{for} Languages @b{use} ("Ada", "C"); 817 @b{for} Source_Dirs @b{use} ("common"); 818 @b{for} Object_Dir @b{use} "obj"; 819 @b{for} Main @b{use} ("main.c"); 820 @b{package} Compiler @b{is} 821 C_Switches := ("-pedantic"); 822 @b{for} Default_Switches ("C") @b{use} C_Switches; 823 @b{for} Default_Switches ("Ada") @b{use} ("-gnaty"); 824 @b{for} Switches ("main.c") @b{use} C_Switches & ("-g"); 825 @b{end} Compiler; 826@b{end} C_Main; 827@end smallexample 828 829@noindent 830This project has many similarities with the previous one. 831As expected, its @code{Main} attribute now refers to a C source. 832The attribute @emph{Exec_Dir} is now omitted, thus the resulting 833executable will be put in the directory @file{obj}. 834 835The most noticeable difference is the use of a variable in the 836@emph{Compiler} package to store settings used in several attributes. 837This avoids text duplication, and eases maintenance (a single place to 838modify if we want to add new switches for C files). We will revisit 839the use of variables in the context of scenarios (@pxref{Scenarios in 840Projects}). 841 842In this example, we see how the file @file{main.c} can be compiled with 843the switches used for all the other C files, plus @option{-g}. 844In this specific situation the use of a variable could have been 845replaced by a reference to the @code{Default_Switches} attribute: 846 847@smallexample @c projectfile 848 @b{for} Switches ("c_main.c") @b{use} Compiler'Default_Switches ("C") & ("-g"); 849@end smallexample 850 851@noindent 852Note the tick (@emph{'}) used to refer to attributes defined in a package. 853 854Here is the output of the GPRbuild command using this project: 855 856@smallexample 857$gprbuild -Pc_main 858gcc -c -pedantic -g main.c 859gcc -c -gnaty proc.adb 860gcc -c -gnaty pack.adb 861gcc -c -pedantic utils.c 862gprbind main.bexch 863... 864gcc main.o -o main 865@end smallexample 866 867@noindent 868The default switches for Ada sources, 869the default switches for C sources (in the compilation of @file{lib.c}), 870and the specific switches for @file{main.c} have all been taken into 871account. 872 873@c --------------------------------------------- 874@node Naming Schemes 875@subsection Naming Schemes 876@c --------------------------------------------- 877 878@noindent 879Sometimes an Ada software system is ported from one compilation environment to 880another (say GNAT), and the file are not named using the default GNAT 881conventions. Instead of changing all the file names, which for a variety of 882reasons might not be possible, you can define the relevant file naming scheme 883in the @b{Naming} package of your project file. 884 885The naming scheme has two distinct goals for the project manager: it 886allows finding of source files when searching in the source 887directories, and given a source file name it makes it possible to guess 888the associated language, and thus the compiler to use. 889 890Note that the use by the Ada compiler of pragmas Source_File_Name is not 891supported when using project files. You must use the features described in this 892paragraph. You can however specify other configuration pragmas. 893 894The following attributes can be defined in package @code{Naming}: 895 896@table @asis 897@item @b{Casing}: 898@cindex @code{Casing} 899 Its value must be one of @code{"lowercase"} (the default if 900 unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the 901 casing of file names with regards to the Ada unit name. Given an Ada unit 902 My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase), 903 @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase). 904 On Windows, file names are case insensitive, so this attribute is 905 irrelevant. 906 907@item @b{Dot_Replacement}: 908@cindex @code{Dot_Replacement} 909 This attribute specifies the string that should replace the "." in unit 910 names. Its default value is @code{"-"} so that a unit 911 @code{Parent.Child} is expected to be found in the file 912 @file{parent-child.adb}. The replacement string must satisfy the following 913 requirements to avoid ambiguities in the naming scheme: 914 915 @itemize - 916 @item It must not be empty 917 @item It cannot start or end with an alphanumeric character 918 @item It cannot be a single underscore 919 @item It cannot start with an underscore followed by an alphanumeric 920 @item It cannot contain a dot @code{'.'} except if the entire string 921 is @code{"."} 922 923 @end itemize 924 925@item @b{Spec_Suffix} and @b{Specification_Suffix}: 926@cindex @code{Spec_Suffix} 927@cindex @code{Specification_Suffix} 928 For Ada, these attributes give the suffix used in file names that contain 929 specifications. For other languages, they give the extension for files 930 that contain declaration (header files in C for instance). The attribute 931 is indexed on the language. 932 The two attributes are equivalent, but the latter is obsolescent. 933 934 If the value of the attribute is the empty string, it indicates to the 935 Project Manager that the only specifications/header files for the language 936 are those specified with attributes @code{Spec} or 937 @code{Specification_Exceptions}. 938 939 If @code{Spec_Suffix ("Ada")} is not specified, then the default is 940 @code{".ads"}. 941 942 A non empty value must satisfy the following requirements: 943 944 @itemize - 945 @item It must include at least one dot 946 @item If @code{Dot_Replacement} is a single dot, then it cannot include 947 more than one dot. 948 @end itemize 949 950@item @b{Body_Suffix} and @b{Implementation_Suffix}: 951@cindex @code{Body_Suffix} 952@cindex @code{Implementation_Suffix} 953 These attributes give the extension used for file names that contain 954 code (bodies in Ada). They are indexed on the language. The second 955 version is obsolescent and fully replaced by the first attribute. 956 957 For each language of a project, one of these two attributes need to be 958 specified, either in the project itself or in the configuration project file. 959 960 If the value of the attribute is the empty string, it indicates to the 961 Project Manager that the only source files for the language 962 are those specified with attributes @code{Body} or 963 @code{Implementation_Exceptions}. 964 965 These attributes must satisfy the same requirements as @code{Spec_Suffix}. 966 In addition, they must be different from any of the values in 967 @code{Spec_Suffix}. 968 If @code{Body_Suffix ("Ada")} is not specified, then the default is 969 @code{".adb"}. 970 971 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the 972 same string, then a file name that ends with the longest of these two 973 suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")} 974 or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}. 975 976 If the suffix does not start with a '.', a file with a name exactly equal to 977 the suffix will also be part of the project (for instance if you define the 978 suffix as @code{Makefile.in}, a file called @file{Makefile.in} will be part 979 of the project. This capability is usually not interesting when building. 980 However, it might become useful when a project is also used to 981 find the list of source files in an editor, like the GNAT Programming System 982 (GPS). 983 984@item @b{Separate_Suffix}: 985@cindex @code{Separate_Suffix} 986 This attribute is specific to Ada. It denotes the suffix used in file names 987 that contain separate bodies. If it is not specified, then it defaults to 988 same value as @code{Body_Suffix ("Ada")}. 989 990 The value of this attribute cannot be the empty string. 991 992 Otherwise, the same rules apply as for the 993 @code{Body_Suffix} attribute. The only accepted index is "Ada". 994 995@item @b{Spec} or @b{Specification}: 996@cindex @code{Spec} 997@cindex @code{Specification} 998 This attribute @code{Spec} can be used to define the source file name for a 999 given Ada compilation unit's spec. The index is the literal name of the Ada 1000 unit (case insensitive). The value is the literal base name of the file that 1001 contains this unit's spec (case sensitive or insensitive depending on the 1002 operating system). This attribute allows the definition of exceptions to the 1003 general naming scheme, in case some files do not follow the usual 1004 convention. 1005 1006 When a source file contains several units, the relative position of the unit 1007 can be indicated. The first unit in the file is at position 1 1008 1009 @smallexample @c projectfile 1010 for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; 1011 for Spec ("top") use "foo.a" at 1; 1012 for Spec ("foo") use "foo.a" at 2; 1013 @end smallexample 1014 1015@item @b{Body} or @b{Implementation}: 1016@cindex @code{Body} 1017@cindex @code{Implementation} 1018 These attribute play the same role as @emph{Spec} for Ada bodies. 1019 1020@item @b{Specification_Exceptions} and @b{Implementation_Exceptions}: 1021@cindex @code{Specification_Exceptions} 1022@cindex @code{Implementation_Exceptions} 1023 These attributes define exceptions to the naming scheme for languages 1024 other than Ada. They are indexed on the language name, and contain 1025 a list of file names respectively for headers and source code. 1026 1027@end table 1028 1029@set unw 1030For example, the following package models the Apex file naming rules: 1031 1032@smallexample @c projectfile 1033@group 1034 @b{package} Naming @b{is} 1035 @b{for} Casing @b{use} "lowercase"; 1036 @b{for} Dot_Replacement @b{use} "."; 1037 @b{for} Spec_Suffix ("Ada") @b{use} ".1.ada"; 1038 @b{for} Body_Suffix ("Ada") @b{use} ".2.ada"; 1039 @b{end} Naming; 1040@end group 1041@end smallexample 1042 1043 1044@c --------------------------------------------- 1045@node Installation 1046@subsection Installation 1047@c --------------------------------------------- 1048 1049@noindent 1050After building an application or a library it is often required to 1051install it into the development environment. For instance this step is 1052required if the library is to be used by another application. 1053The @command{gprinstall} tool provides an easy way to install 1054libraries, executable or object code generated during the build. The 1055@b{Install} package can be used to change the default locations. 1056 1057The following attributes can be defined in package @code{Install}: 1058 1059@table @asis 1060 1061@item @b{Active} 1062 1063Whether the project is to be installed, values are @code{true} 1064(default) or @code{false}. 1065 1066@item @b{Artifacts} 1067@cindex @code{Artifacts} 1068 1069An array attribute to declare a set of files not part of the sources 1070to be installed. The array discriminant is the directory where the 1071file is to be installed. If a relative directory then Prefix (see 1072below) is prepended. 1073 1074@item @b{Prefix}: 1075@cindex @code{Prefix} 1076 1077Root directory for the installation. 1078 1079@item @b{Exec_Subdir} 1080 1081Subdirectory of @b{Prefix} where executables are to be 1082installed. Default is @b{bin}. 1083 1084@item @b{Lib_Subdir} 1085 1086Subdirectory of @b{Prefix} where directory with the library or object 1087files is to be installed. Default is @b{lib}. 1088 1089@item @b{Sources_Subdir} 1090 1091Subdirectory of @b{Prefix} where directory with sources is to be 1092installed. Default is @b{include}. 1093 1094@item @b{Project_Subdir} 1095 1096Subdirectory of @b{Prefix} where the generated project file is to be 1097installed. Default is @b{share/gpr}. 1098 1099@item @b{Mode} 1100 1101The installation mode, it is either @b{dev} (default) or @b{usage}. 1102See @b{gprbuild} user's guide for details. 1103 1104@item @b{Install_Name} 1105 1106Specify the name to use for recording the installation. The default is 1107the project name without the extension. 1108@end table 1109 1110@c --------------------------------------------- 1111@node Distributed support 1112@subsection Distributed support 1113@c --------------------------------------------- 1114 1115@noindent 1116For large projects the compilation time can become a limitation in 1117the development cycle. To cope with that, GPRbuild supports 1118distributed compilation. 1119 1120The following attributes can be defined in package @code{Remote}: 1121 1122@table @asis 1123 1124@item @b{Root_Dir}: 1125@cindex @code{Root_Dir} 1126 1127Root directory of the project's sources. The default value is the 1128project's directory. 1129 1130@end table 1131 1132@c --------------------------------------------- 1133@node Organizing Projects into Subsystems 1134@section Organizing Projects into Subsystems 1135@c --------------------------------------------- 1136 1137@noindent 1138A @b{subsystem} is a coherent part of the complete system to be built. It is 1139represented by a set of sources and one single object directory. A system can 1140be composed of a single subsystem when it is simple as we have seen in the 1141first section. Complex systems are usually composed of several interdependent 1142subsystems. A subsystem is dependent on another subsystem if knowledge of the 1143other one is required to build it, and in particular if visibility on some of 1144the sources of this other subsystem is required. Each subsystem is usually 1145represented by its own project file. 1146 1147In this section, the previous example is being extended. Let's assume some 1148sources of our @code{Build} project depend on other sources. 1149For instance, when building a graphical interface, it is usual to depend upon 1150a graphical library toolkit such as GtkAda. Furthermore, we also need 1151sources from a logging module we had previously written. 1152 1153@menu 1154* Project Dependencies:: 1155* Cyclic Project Dependencies:: 1156* Sharing Between Projects:: 1157* Global Attributes:: 1158@end menu 1159 1160@c --------------------------------------------- 1161@node Project Dependencies 1162@subsection Project Dependencies 1163@c --------------------------------------------- 1164 1165@noindent 1166GtkAda comes with its own project file (appropriately called 1167@file{gtkada.gpr}), and we will assume we have already built a project 1168called @file{logging.gpr} for the logging module. With the information provided 1169so far in @file{build.gpr}, building the application would fail with an error 1170indicating that the gtkada and logging units that are relied upon by the sources 1171of this project cannot be found. 1172 1173This is solved by adding the following @b{with} clauses at the beginning of our 1174project: 1175 1176@smallexample @c projectfile 1177 @b{with} "gtkada.gpr"; 1178 @b{with} "a/b/logging.gpr"; 1179 @b{project} Build @b{is} 1180 ... --@i{ as before} 1181 @b{end} Build; 1182@end smallexample 1183 1184@noindent 1185@cindex @code{Externally_Built} 1186When such a project is compiled, @command{gprbuild} will automatically check 1187the other projects and recompile their sources when needed. It will also 1188recompile the sources from @code{Build} when needed, and finally create the 1189executable. In some cases, the implementation units needed to recompile a 1190project are not available, or come from some third party and you do not want to 1191recompile it yourself. In this case, set the attribute @b{Externally_Built} to 1192"true", indicating to the builder that this project can be assumed to be 1193up-to-date, and should not be considered for recompilation. In Ada, if the 1194sources of this externally built project were compiled with another version of 1195the compiler or with incompatible options, the binder will issue an error. 1196 1197The project's @code{with} clause has several effects. It provides source 1198visibility between projects during the compilation process. It also guarantees 1199that the necessary object files from @code{Logging} and @code{GtkAda} are 1200available when linking @code{Build}. 1201 1202As can be seen in this example, the syntax for importing projects is similar 1203to the syntax for importing compilation units in Ada. However, project files 1204use literal strings instead of names, and the @code{with} clause identifies 1205project files rather than packages. 1206 1207Each literal string after @code{with} is the path 1208(absolute or relative) to a project file. The @code{.gpr} extension is 1209optional, although we recommend adding it. If no extension is specified, 1210and no project file with the @file{.gpr} extension is found, then 1211the file is searched for exactly as written in the @code{with} clause, 1212that is with no extension. 1213 1214As mentioned above, the path after a @code{with} has to be a literal 1215string, and you cannot use concatenation, or lookup the value of external 1216variables to change the directories from which a project is loaded. 1217A solution if you need something like this is to use aggregate projects 1218(@pxref{Aggregate Projects}). 1219 1220@cindex project path 1221When a relative path or a base name is used, the 1222project files are searched relative to each of the directories in the 1223@b{project path}. This path includes all the directories found with the 1224following algorithm, in this order; the first matching file is used: 1225 1226@itemize @bullet 1227@item First, the file is searched relative to the directory that contains the 1228 current project file. 1229 1230@item 1231@cindex @code{GPR_PROJECT_PATH_FILE} 1232@cindex @code{GPR_PROJECT_PATH} 1233@cindex @code{ADA_PROJECT_PATH} 1234 Then it is searched relative to all the directories specified in the 1235 environment variables @b{GPR_PROJECT_PATH_FILE}, 1236 @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH} (in that order) if they exist. 1237 The value of @b{GPR_PROJECT_PATH_FILE}, when defined, is the path name of 1238 a text file that contains project directory path names, one per line. 1239 @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH}, when defined, contain 1240 project directory path names separated by directory separators. 1241 @b{ADA_PROJECT_PATH} is used for compatibility, it is recommended to 1242 use @b{GPR_PROJECT_PATH_FILE} or @b{GPR_PROJECT_PATH}. 1243 1244@item Finally, it is searched relative to the default project directories. 1245 Such directories depend on the tool used. The locations searched in the 1246 specified order are: 1247 1248 @itemize @bullet 1249 @item @file{<prefix>/<target>/lib/gnat} 1250 (for @command{gnatmake} in all cases, and for @command{gprbuild} if option 1251 @option{--target} is specified) 1252 @item @file{<prefix>/<target>/share/gpr} 1253 (for @command{gnatmake} in all cases, and for @command{gprbuild} if option 1254 @option{--target} is specified) 1255 @item @file{<prefix>/share/gpr/} 1256 (for @command{gnatmake} and @command{gprbuild}) 1257 @item @file{<prefix>/lib/gnat/} 1258 (for @command{gnatmake} and @command{gprbuild}) 1259 @end itemize 1260 1261 In our example, @file{gtkada.gpr} is found in the predefined directory if 1262 it was installed at the same root as GNAT. 1263@end itemize 1264 1265@noindent 1266Some tools also support extending the project path from the command line, 1267generally through the @option{-aP}. You can see the value of the project 1268path by using the @command{gnatls -v} command. 1269 1270Any symbolic link will be fully resolved in the directory of the 1271importing project file before the imported project file is examined. 1272 1273Any source file in the imported project can be used by the sources of the 1274importing project, transitively. 1275Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of 1276@code{A} may depend on the sources of @code{C}, even if @code{A} does not 1277import @code{C} explicitly. However, this is not recommended, because if 1278and when @code{B} ceases to import @code{C}, some sources in @code{A} will 1279no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports} 1280that will report such indirect dependencies. 1281 1282One very important aspect of a project hierarchy is that 1283@b{a given source can only belong to one project} (otherwise the project manager 1284would not know which settings apply to it and when to recompile it). It means 1285that different project files do not usually share source directories or 1286when they do, they need to specify precisely which project owns which sources 1287using attribute @code{Source_Files} or equivalent. By contrast, 2 projects 1288can each own a source with the same base file name as long as they live in 1289different directories. The latter is not true for Ada Sources because of the 1290correlation between source files and Ada units. 1291 1292@c --------------------------------------------- 1293@node Cyclic Project Dependencies 1294@subsection Cyclic Project Dependencies 1295@c --------------------------------------------- 1296 1297@noindent 1298Cyclic dependencies are mostly forbidden: 1299if @code{A} imports @code{B} (directly or indirectly) then @code{B} 1300is not allowed to import @code{A}. However, there are cases when cyclic 1301dependencies would be beneficial. For these cases, another form of import 1302between projects exists: the @b{limited with}. A project @code{A} that 1303imports a project @code{B} with a straight @code{with} may also be imported, 1304directly or indirectly, by @code{B} through a @code{limited with}. 1305 1306The difference between straight @code{with} and @code{limited with} is that 1307the name of a project imported with a @code{limited with} cannot be used in the 1308project importing it. In particular, its packages cannot be renamed and 1309its variables cannot be referred to. 1310 1311@smallexample @c 0projectfile 1312with "b.gpr"; 1313with "c.gpr"; 1314project A is 1315 For Exec_Dir use B'Exec_Dir; -- ok 1316end A; 1317 1318limited with "a.gpr"; -- Cyclic dependency: A -> B -> A 1319project B is 1320 For Exec_Dir use A'Exec_Dir; -- not ok 1321end B; 1322 1323with "d.gpr"; 1324project C is 1325end C; 1326 1327limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A 1328project D is 1329 For Exec_Dir use A'Exec_Dir; -- not ok 1330end D; 1331@end smallexample 1332 1333@c --------------------------------------------- 1334@node Sharing Between Projects 1335@subsection Sharing Between Projects 1336@c --------------------------------------------- 1337 1338@noindent 1339When building an application, it is common to have similar needs in several of 1340the projects corresponding to the subsystems under construction. For instance, 1341they will all have the same compilation switches. 1342 1343As seen before (@pxref{Tools Options in Project Files}), setting compilation 1344switches for all sources of a subsystem is simple: it is just a matter of 1345adding a @code{Compiler.Default_Switches} attribute to each project files with 1346the same value. Of course, that means duplication of data, and both places need 1347to be changed in order to recompile the whole application with different 1348switches. It can become a real problem if there are many subsystems and thus 1349many project files to edit. 1350 1351There are two main approaches to avoiding this duplication: 1352 1353@itemize @bullet 1354@item Since @file{build.gpr} imports @file{logging.gpr}, we could change it 1355 to reference the attribute in Logging, either through a package renaming, 1356 or by referencing the attribute. The following example shows both cases: 1357 1358 @smallexample @c projectfile 1359 project Logging is 1360 package Compiler is 1361 for Switches ("Ada") 1362 use ("-O2"); 1363 end Compiler; 1364 package Binder is 1365 for Switches ("Ada") 1366 use ("-E"); 1367 end Binder; 1368 end Logging; 1369 1370 with "logging.gpr"; 1371 project Build is 1372 package Compiler renames Logging.Compiler; 1373 package Binder is 1374 for Switches ("Ada") use Logging.Binder'Switches ("Ada"); 1375 end Binder; 1376 end Build; 1377 @end smallexample 1378 1379 @noindent 1380 The solution used for @code{Compiler} gets the same value for all 1381 attributes of the package, but you cannot modify anything from the 1382 package (adding extra switches or some exceptions). The second 1383 version is more flexible, but more verbose. 1384 1385 If you need to refer to the value of a variable in an imported 1386 project, rather than an attribute, the syntax is similar but uses 1387 a "." rather than an apostrophe. For instance: 1388 1389 @smallexample @c projectfile 1390 with "imported"; 1391 project Main is 1392 Var1 := Imported.Var; 1393 end Main; 1394 @end smallexample 1395 1396@item The second approach is to define the switches in a third project. 1397 That project is set up without any sources (so that, as opposed to 1398 the first example, none of the project plays a special role), and 1399 will only be used to define the attributes. Such a project is 1400 typically called @file{shared.gpr}. 1401 1402 @smallexample @c projectfile 1403 abstract project Shared is 1404 for Source_Files use (); -- no sources 1405 package Compiler is 1406 for Switches ("Ada") 1407 use ("-O2"); 1408 end Compiler; 1409 end Shared; 1410 1411 with "shared.gpr"; 1412 project Logging is 1413 package Compiler renames Shared.Compiler; 1414 end Logging; 1415 1416 with "shared.gpr"; 1417 project Build is 1418 package Compiler renames Shared.Compiler; 1419 end Build; 1420 @end smallexample 1421 1422 @noindent 1423 As for the first example, we could have chosen to set the attributes 1424 one by one rather than to rename a package. The reason we explicitly 1425 indicate that @code{Shared} has no sources is so that it can be created 1426 in any directory and we are sure it shares no sources with @code{Build} 1427 or @code{Logging}, which of course would be invalid. 1428 1429@cindex project qualifier 1430 Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}. 1431 This qualifier is optional, but helps convey the message that we do not 1432 intend this project to have sources (@pxref{Qualified Projects} for 1433 more qualifiers). 1434@end itemize 1435 1436@c --------------------------------------------- 1437@node Global Attributes 1438@subsection Global Attributes 1439@c --------------------------------------------- 1440 1441@noindent 1442We have already seen many examples of attributes used to specify a special 1443option of one of the tools involved in the build process. Most of those 1444attributes are project specific. That it to say, they only affect the invocation 1445of tools on the sources of the project where they are defined. 1446 1447There are a few additional attributes that apply to all projects in a 1448hierarchy as long as they are defined on the "main" project. 1449The main project is the project explicitly mentioned on the command-line. 1450The project hierarchy is the "with"-closure of the main project. 1451 1452Here is a list of commonly used global attributes: 1453 1454@table @asis 1455@item @b{Builder.Global_Configuration_Pragmas}: 1456@cindex @code{Global_Configuration_Pragmas} 1457 This attribute points to a file that contains configuration pragmas 1458 to use when building executables. These pragmas apply for all 1459 executables built from this project hierarchy. As we have seen before, 1460 additional pragmas can be specified on a per-project basis by setting the 1461 @code{Compiler.Local_Configuration_Pragmas} attribute. 1462 1463@item @b{Builder.Global_Compilation_Switches}: 1464@cindex @code{Global_Compilation_Switches} 1465 This attribute is a list of compiler switches to use when compiling any 1466 source file in the project hierarchy. These switches are used in addition 1467 to the ones defined in the @code{Compiler} package, which only apply to 1468 the sources of the corresponding project. This attribute is indexed on 1469 the name of the language. 1470 1471@end table 1472 1473Using such global capabilities is convenient. It can also lead to unexpected 1474behavior. Especially when several subsystems are shared among different main 1475projects and the different global attributes are not 1476compatible. Note that using aggregate projects can be a safer and more powerful 1477replacement to global attributes. 1478 1479@c --------------------------------------------- 1480@node Scenarios in Projects 1481@section Scenarios in Projects 1482@c --------------------------------------------- 1483 1484@noindent 1485Various aspects of the projects can be modified based on @b{scenarios}. These 1486are user-defined modes that change the behavior of a project. Typical 1487examples are the setup of platform-specific compiler options, or the use of 1488a debug and a release mode (the former would activate the generation of debug 1489information, while the second will focus on improving code optimization). 1490 1491Let's enhance our example to support debug and release modes. The issue is to 1492let the user choose what kind of system he is building: use @option{-g} as 1493compiler switches in debug mode and @option{-O2} in release mode. We will also 1494set up the projects so that we do not share the same object directory in both 1495modes; otherwise switching from one to the other might trigger more 1496recompilations than needed or mix objects from the two modes. 1497 1498One naive approach is to create two different project files, say 1499@file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate 1500attributes as explained in previous sections. This solution does not scale 1501well, because in the presence of multiple projects depending on each other, you 1502will also have to duplicate the complete hierarchy and adapt the project files 1503to point to the right copies. 1504 1505@cindex scenarios 1506Instead, project files support the notion of scenarios controlled 1507by external values. Such values can come from several sources (in decreasing 1508order of priority): 1509 1510@table @asis 1511@item @b{Command line}: 1512@cindex @option{-X} 1513 When launching @command{gnatmake} or @command{gprbuild}, the user can pass 1514 extra @option{-X} switches to define the external value. In 1515 our case, the command line might look like 1516 1517 @smallexample 1518 gnatmake -Pbuild.gpr -Xmode=debug 1519 or gnatmake -Pbuild.gpr -Xmode=release 1520 @end smallexample 1521 1522@item @b{Environment variables}: 1523 When the external value does not come from the command line, it can come from 1524 the value of environment variables of the appropriate name. 1525 In our case, if an environment variable called "mode" 1526 exists, its value will be taken into account. 1527 1528@item @b{External function second parameter}. 1529 1530@end table 1531 1532@cindex @code{external} 1533We now need to get that value in the project. The general form is to use 1534the predefined function @b{external} which returns the current value of 1535the external. For instance, we could set up the object directory to point to 1536either @file{obj/debug} or @file{obj/release} by changing our project to 1537 1538@smallexample @c projectfile 1539 @b{project} Build @b{is} 1540 @b{for} Object_Dir @b{use} "obj/" & @b{external} ("mode", "debug"); 1541 ... --@i{ as before} 1542 @b{end} Build; 1543@end smallexample 1544 1545@noindent 1546The second parameter to @code{external} is optional, and is the default 1547value to use if "mode" is not set from the command line or the environment. 1548 1549In order to set the switches according to the different scenarios, other 1550constructs have to be introduced such as typed variables and case constructions. 1551 1552@cindex typed variable 1553@cindex case construction 1554A @b{typed variable} is a variable that 1555can take only a limited number of values, similar to an enumeration in Ada. 1556Such a variable can then be used in a @b{case construction} and create conditional 1557sections in the project. The following example shows how this can be done: 1558 1559@smallexample @c projectfile 1560 @b{project} Build @b{is} 1561 @b{type} Mode_Type @b{is} ("debug", "release"); --@i{ all possible values} 1562 Mode : Mode_Type := @b{external} ("mode", "debug"); --@i{ a typed variable} 1563 1564 @b{package} Compiler @b{is} 1565 @b{case} Mode @b{is} 1566 @b{when} "debug" => 1567 @b{for} Switches ("Ada") 1568 @b{use} ("-g"); 1569 @b{when} "release" => 1570 @b{for} Switches ("Ada") 1571 @b{use} ("-O2"); 1572 @b{end} @b{case}; 1573 @b{end} Compiler; 1574 @b{end} Build; 1575@end smallexample 1576 1577@noindent 1578The project has suddenly grown in size, but has become much more flexible. 1579@code{Mode_Type} defines the only valid values for the @code{mode} variable. If 1580any other value is read from the environment, an error is reported and the 1581project is considered as invalid. 1582 1583The @code{Mode} variable is initialized with an external value 1584defaulting to @code{"debug"}. This default could be omitted and that would 1585force the user to define the value. Finally, we can use a case construction to set the 1586switches depending on the scenario the user has chosen. 1587 1588Most aspects of the projects can depend on scenarios. The notable exception 1589are project dependencies (@code{with} clauses), which cannot depend on a scenario. 1590 1591Scenarios work the same way with @b{project hierarchies}: you can either 1592duplicate a variable similar to @code{Mode} in each of the project (as long 1593as the first argument to @code{external} is always the same and the type is 1594the same), or simply set the variable in the @file{shared.gpr} project 1595(@pxref{Sharing Between Projects}). 1596 1597@c --------------------------------------------- 1598@node Library Projects 1599@section Library Projects 1600@c --------------------------------------------- 1601 1602@noindent 1603So far, we have seen examples of projects that create executables. However, 1604it is also possible to create libraries instead. A @b{library} is a specific 1605type of subsystem where, for convenience, objects are grouped together 1606using system-specific means such as archives or windows DLLs. 1607 1608Library projects provide a system- and language-independent way of building both @b{static} 1609and @b{dynamic} libraries. They also support the concept of @b{standalone 1610libraries} (SAL) which offer two significant properties: the elaboration 1611(e.g. initialization) of the library is either automatic or very simple; 1612a change in the 1613implementation part of the library implies minimal post-compilation actions on 1614the complete system and potentially no action at all for the rest of the 1615system in the case of dynamic SALs. 1616 1617There is a restriction on shared library projects: by default, they are only 1618allowed to import other shared library projects. They are not allowed to 1619import non library projects or static library projects. 1620 1621The GNAT Project Manager takes complete care of the library build, rebuild and 1622installation tasks, including recompilation of the source files for which 1623objects do not exist or are not up to date, assembly of the library archive, and 1624installation of the library (i.e., copying associated source, object and 1625@file{ALI} files to the specified location). 1626 1627@menu 1628* Building Libraries:: 1629* Using Library Projects:: 1630* Stand-alone Library Projects:: 1631* Installing a library with project files:: 1632@end menu 1633 1634@c --------------------------------------------- 1635@node Building Libraries 1636@subsection Building Libraries 1637@c --------------------------------------------- 1638 1639@noindent 1640Let's enhance our example and transform the @code{logging} subsystem into a 1641library. In order to do so, a few changes need to be made to 1642@file{logging.gpr}. Some attributes need to be defined: at least 1643@code{Library_Name} and @code{Library_Dir}; in addition, some other attributes 1644can be used to specify specific aspects of the library. For readability, it is 1645also recommended (although not mandatory), to use the qualifier @code{library} 1646in front of the @code{project} keyword. 1647 1648@table @asis 1649@item @b{Library_Name}: 1650@cindex @code{Library_Name} 1651 This attribute is the name of the library to be built. There is no 1652 restriction on the name of a library imposed by the project manager, except 1653 for stand-alone libraries whose names must follow the syntax of Ada 1654 identifiers; however, there may be system-specific restrictions on the name. 1655 In general, it is recommended to stick to alphanumeric characters (and 1656 possibly single underscores) to help portability. 1657 1658@item @b{Library_Dir}: 1659@cindex @code{Library_Dir} 1660 This attribute is the path (absolute or relative) of the directory where 1661 the library is to be installed. In the process of building a library, 1662 the sources are compiled, the object files end up in the explicit or 1663 implicit @code{Object_Dir} directory. When all sources of a library 1664 are compiled, some of the compilation artifacts, including the library itself, 1665 are copied to the library_dir directory. This directory must exist and be 1666 writable. It must also be different from the object directory so that cleanup 1667 activities in the Library_Dir do not affect recompilation needs. 1668 1669@end table 1670 1671Here is the new version of @file{logging.gpr} that makes it a library: 1672 1673@smallexample @c projectfile 1674library @b{project} Logging @b{is} --@i{ "library" is optional} 1675 @b{for} Library_Name @b{use} "logging"; --@i{ will create "liblogging.a" on Unix} 1676 @b{for} Object_Dir @b{use} "obj"; 1677 @b{for} Library_Dir @b{use} "lib"; --@i{ different from object_dir} 1678@b{end} Logging; 1679@end smallexample 1680 1681@noindent 1682Once the above two attributes are defined, the library project is valid and 1683is enough for building a library with default characteristics. 1684Other library-related attributes can be used to change the defaults: 1685 1686@table @asis 1687@item @b{Library_Kind}: 1688@cindex @code{Library_Kind} 1689 The value of this attribute must be either @code{"static"}, @code{"dynamic"} or 1690 @code{"relocatable"} (the latter is a synonym for dynamic). It indicates 1691 which kind of library should be built (the default is to build a 1692 static library, that is an archive of object files that can potentially 1693 be linked into a static executable). When the library is set to be dynamic, 1694 a separate image is created that will be loaded independently, usually 1695 at the start of the main program execution. Support for dynamic libraries is 1696 very platform specific, for instance on Windows it takes the form of a DLL 1697 while on GNU/Linux, it is a dynamic elf image whose suffix is usually 1698 @file{.so}. Library project files, on the other hand, can be written in 1699 a platform independent way so that the same project file can be used to build 1700 a library on different operating systems. 1701 1702 If you need to build both a static and a dynamic library, it is recommended 1703 to use two different object directories, since in some cases some extra code 1704 needs to be generated for the latter. For such cases, one can either define 1705 two different project files, or a single one that uses scenarios to indicate 1706 the various kinds of library to be built and their corresponding object_dir. 1707 1708@cindex @code{Library_ALI_Dir} 1709@item @b{Library_ALI_Dir}: 1710 This attribute may be specified to indicate the directory where the ALI 1711 files of the library are installed. By default, they are copied into the 1712 @code{Library_Dir} directory, but as for the executables where we have a 1713 separate @code{Exec_Dir} attribute, you might want to put them in a separate 1714 directory since there can be hundreds of them. The same restrictions as for 1715 the @code{Library_Dir} attribute apply. 1716 1717@cindex @code{Library_Version} 1718@item @b{Library_Version}: 1719 This attribute is platform dependent, and has no effect on Windows. 1720 On Unix, it is used only for dynamic libraries as the internal 1721 name of the library (the @code{"soname"}). If the library file name (built 1722 from the @code{Library_Name}) is different from the @code{Library_Version}, 1723 then the library file will be a symbolic link to the actual file whose name 1724 will be @code{Library_Version}. This follows the usual installation schemes 1725 for dynamic libraries on many Unix systems. 1726 1727@smallexample @c projectfile 1728@group 1729 @b{project} Logging @b{is} 1730 Version := "1"; 1731 @b{for} Library_Dir @b{use} "lib"; 1732 @b{for} Library_Name @b{use} "logging"; 1733 @b{for} Library_Kind @b{use} "dynamic"; 1734 @b{for} Library_Version @b{use} "liblogging.so." & Version; 1735 @b{end} Logging; 1736@end group 1737@end smallexample 1738 1739 @noindent 1740 After the compilation, the directory @file{lib} will contain both a 1741 @file{libdummy.so.1} library and a symbolic link to it called 1742 @file{libdummy.so}. 1743 1744@cindex @code{Library_GCC} 1745@item @b{Library_GCC}: 1746 This attribute is the name of the tool to use instead of "gcc" to link shared 1747 libraries. A common use of this attribute is to define a wrapper script that 1748 accomplishes specific actions before calling gcc (which itself calls the 1749 linker to build the library image). 1750 1751@item @b{Library_Options}: 1752@cindex @code{Library_Options} 1753 This attribute may be used to specify additional switches (last switches) 1754 when linking a shared library. 1755 1756 It may also be used to add foreign object files to a static library. 1757 Each string in Library_Options is an absolute or relative path of an object 1758 file. When a relative path, it is relative to the object directory. 1759 1760@item @b{Leading_Library_Options}: 1761@cindex @code{Leading_Library_Options} 1762 This attribute, that is taken into account only by @command{gprbuild}, may be 1763 used to specified leading options (first switches) when linking a shared 1764 library. 1765 1766@cindex @code{Linker_Options} 1767@item @b{Linker.Linker_Options}: 1768 This attribute specifies additional switches to be given to the linker when 1769 linking an executable. It is ignored when defined in the main project and 1770 taken into account in all other projects that are imported directly or 1771 indirectly. These switches complement the @code{Linker.Switches} 1772 defined in the main project. This is useful when a particular subsystem 1773 depends on an external library: adding this dependency as a 1774 @code{Linker_Options} in the project of the subsystem is more convenient than 1775 adding it to all the @code{Linker.Switches} of the main projects that depend 1776 upon this subsystem. 1777@end table 1778 1779@c --------------------------------------------- 1780@node Using Library Projects 1781@subsection Using Library Projects 1782@c --------------------------------------------- 1783 1784@noindent 1785When the builder detects that a project file is a library project file, it 1786recompiles all sources of the project that need recompilation and rebuild the 1787library if any of the sources have been recompiled. It then groups all object 1788files into a single file, which is a shared or a static library. This library 1789can later on be linked with multiple executables. Note that the use 1790of shard libraries reduces the size of the final executable and can also reduce 1791the memory footprint at execution time when the library is shared among several 1792executables. 1793 1794It is also possible to build @b{multi-language libraries}. When using 1795@command{gprbuild} as a builder, multi-language library projects allow naturally 1796the creation of multi-language libraries . @command{gnatmake}, does not try to 1797compile non Ada sources. However, when the project is multi-language, it will 1798automatically link all object files found in the object directory, whether or 1799not they were compiled from an Ada source file. This specific behavior does not 1800apply to Ada-only projects which only take into account the objects 1801corresponding to the sources of the project. 1802 1803A non-library project can import a library project. When the builder is invoked 1804on the former, the library of the latter is only rebuilt when absolutely 1805necessary. For instance, if a unit of the library is not up-to-date but none of 1806the executables need this unit, then the unit is not recompiled and the library 1807is not reassembled. For instance, let's assume in our example that logging has 1808the following sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and 1809@file{log2.adb}. If @file{log1.adb} has been modified, then the library 1810@file{liblogging} will be rebuilt when compiling all the sources of 1811@code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb} 1812include a @code{"with Log1"}. 1813 1814To ensure that all the sources in the @code{Logging} library are 1815up to date, and that all the sources of @code{Build} are also up to date, 1816the following two commands need to be used: 1817 1818@smallexample 1819gnatmake -Plogging.gpr 1820gnatmake -Pbuild.gpr 1821@end smallexample 1822 1823@noindent 1824All @file{ALI} files will also be copied from the object directory to the 1825library directory. To build executables, @command{gnatmake} will use the 1826library rather than the individual object files. 1827 1828Library projects can also be useful to describe a library that needs to be used 1829but, for some reason, cannot be rebuilt. For instance, it is the case when some 1830of the library sources are not available. Such library projects need to use the 1831@code{Externally_Built} attribute as in the example below: 1832 1833@smallexample @c projectfile 1834library @b{project} Extern_Lib @b{is} 1835 @b{for} Languages @b{use} ("Ada", "C"); 1836 @b{for} Source_Dirs @b{use} ("lib_src"); 1837 @b{for} Library_Dir @b{use} "lib2"; 1838 @b{for} Library_Kind @b{use} "dynamic"; 1839 @b{for} Library_Name @b{use} "l2"; 1840 @b{for} Externally_Built @b{use} "true"; --@i{ <<<<} 1841@b{end} Extern_Lib; 1842@end smallexample 1843 1844@noindent 1845In the case of externally built libraries, the @code{Object_Dir} 1846attribute does not need to be specified because it will never be 1847used. 1848 1849The main effect of using such an externally built library project is mostly to 1850affect the linker command in order to reference the desired library. It can 1851also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches} 1852in the project corresponding to the subsystem needing this external library. 1853This latter method is more straightforward in simple cases but when several 1854subsystems depend upon the same external library, finding the proper place 1855for the @code{Linker.Linker_Options} might not be easy and if it is 1856not placed properly, the final link command is likely to present ordering issues. 1857In such a situation, it is better to use the externally built library project 1858so that all other subsystems depending on it can declare this dependency thanks 1859to a project @code{with} clause, which in turn will trigger the builder to find 1860the proper order of libraries in the final link command. 1861 1862@c --------------------------------------------- 1863@node Stand-alone Library Projects 1864@subsection Stand-alone Library Projects 1865@c --------------------------------------------- 1866 1867@noindent 1868@cindex standalone libraries 1869A @b{stand-alone library} is a library that contains the necessary code to 1870elaborate the Ada units that are included in the library. A stand-alone 1871library is a convenient way to add an Ada subsystem to a more global system 1872whose main is not in Ada since it makes the elaboration of the Ada part mostly 1873transparent. However, stand-alone libraries are also useful when the main is in 1874Ada: they provide a means for minimizing relinking & redeployment of complex 1875systems when localized changes are made. 1876 1877The name of a stand-alone library, specified with attribute 1878@code{Library_Name}, must have the syntax of an Ada identifier. 1879 1880The most prominent characteristic of a stand-alone library is that it offers a 1881distinction between interface units and implementation units. Only the former 1882are visible to units outside the library. A stand-alone library project is thus 1883characterised by a third attribute, usually @b{Library_Interface}, in addition 1884to the two attributes that make a project a Library Project 1885(@code{Library_Name} and @code{Library_Dir}). This third attribute may also be 1886@b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada 1887and takes a list of units as parameter. @b{Interfaces} works for any supported 1888language and takes a list of sources as parameter. 1889 1890@table @asis 1891@item @b{Library_Interface}: 1892@cindex @code{Library_Interface} 1893 This attribute defines an explicit subset of the units of the project. Units 1894 from projects importing this library project may only "with" units whose 1895 sources are listed in the @code{Library_Interface}. Other sources are 1896 considered implementation units. 1897 1898@smallexample @c projectfile 1899@group 1900 @b{for} Library_Dir @b{use} "lib"; 1901 @b{for} Library_Name @b{use} "logging"; 1902 @b{for} Library_Interface @b{use} ("lib1", "lib2"); --@i{ unit names} 1903@end group 1904@end smallexample 1905 1906@item @b{Interfaces} 1907 This attribute defines an explicit subset of the source files of a project. 1908 Sources from projects importing this project, can only depend on sources from 1909 this subset. This attribute can be used on non library projects. It can also 1910 be used as a replacement for attribute @code{Library_Interface}, in which 1911 case, units have to be replaced by source files. For multi-language library 1912 projects, it is the only way to make the project a Stand-Alone Library project 1913 whose interface is not purely Ada. 1914 1915@item @b{Library_Standalone}: 1916@cindex @code{Library_Standalone} 1917 This attribute defines the kind of standalone library to 1918 build. Values are either @code{standard} (the default), @code{no} or 1919 @code{encapsulated}. When @code{standard} is used the code to elaborate and 1920 finalize the library is embedded, when @code{encapsulated} is used the 1921 library can furthermore depend only on static libraries (including 1922 the GNAT runtime). This attribute can be set to @code{no} to make it clear 1923 that the library should not be standalone in which case the 1924 @code{Library_Interface} should not defined. Note that this attribute 1925 only applies to shared libraries, so @code{Library_Kind} must be set 1926 to @code{dynamic}. 1927 1928@smallexample @c projectfile 1929@group 1930 @b{for} Library_Dir @b{use} "lib"; 1931 @b{for} Library_Name @b{use} "logging"; 1932 @b{for} Library_Kind @b{use} "dynamic"; 1933 @b{for} Library_Interface @b{use} ("lib1", "lib2"); --@i{ unit names} 1934 @b{for} Library_Standalone @b{use} "encapsulated"; 1935@end group 1936@end smallexample 1937 1938@end table 1939 1940In order to include the elaboration code in the stand-alone library, the binder 1941is invoked on the closure of the library units creating a package whose name 1942depends on the library name (b~logging.ads/b in the example). 1943This binder-generated package includes @b{initialization} and @b{finalization} 1944procedures whose names depend on the library name (@code{logginginit} and 1945@code{loggingfinal} in the example). The object corresponding to this package is 1946included in the library. 1947 1948@table @asis 1949@item @b{Library_Auto_Init}: 1950@cindex @code{Library_Auto_Init} 1951 A dynamic stand-alone Library is automatically initialized 1952 if automatic initialization of Stand-alone Libraries is supported on the 1953 platform and if attribute @b{Library_Auto_Init} is not specified or 1954 is specified with the value "true". A static Stand-alone Library is never 1955 automatically initialized. Specifying "false" for this attribute 1956 prevents automatic initialization. 1957 1958 When a non-automatically initialized stand-alone library is used in an 1959 executable, its initialization procedure must be called before any service of 1960 the library is used. When the main subprogram is in Ada, it may mean that the 1961 initialization procedure has to be called during elaboration of another 1962 package. 1963 1964@item @b{Library_Dir}: 1965@cindex @code{Library_Dir} 1966 For a stand-alone library, only the @file{ALI} files of the interface units 1967 (those that are listed in attribute @code{Library_Interface}) are copied to 1968 the library directory. As a consequence, only the interface units may be 1969 imported from Ada units outside of the library. If other units are imported, 1970 the binding phase will fail. 1971 1972@item @b{Binder.Default_Switches}: 1973 When a stand-alone library is bound, the switches that are specified in 1974 the attribute @b{Binder.Default_Switches ("Ada")} are 1975 used in the call to @command{gnatbind}. 1976 1977@item @b{Library_Src_Dir}: 1978@cindex @code{Library_Src_Dir} 1979 This attribute defines the location (absolute or relative to the project 1980 directory) where the sources of the interface units are copied at 1981 installation time. 1982 These sources includes the specs of the interface units along with the 1983 closure of sources necessary to compile them successfully. That may include 1984 bodies and subunits, when pragmas @code{Inline} are used, or when there are 1985 generic units in specs. This directory cannot point to the object directory 1986 or one of the source directories, but it can point to the library directory, 1987 which is the default value for this attribute. 1988 1989@item @b{Library_Symbol_Policy}: 1990@cindex @code{Library_Symbol_Policy} 1991 This attribute controls the export of symbols and, on some platforms (like 1992 VMS) that have the notions of major and minor IDs built in the library 1993 files, it controls the setting of these IDs. It is not supported on all 1994 platforms (where it will just have no effect). It may have one of the 1995 following values: 1996 1997 @itemize - 1998 @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled 1999 @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File} 2000 is not defined, then it is equivalent to policy "autonomous". If there 2001 are exported symbols in the reference symbol file that are not in the 2002 object files of the interfaces, the major ID of the library is increased. 2003 If there are symbols in the object files of the interfaces that are not 2004 in the reference symbol file, these symbols are put at the end of the list 2005 in the newly created symbol file and the minor ID is increased. 2006 @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be 2007 defined. The library will fail to build if the exported symbols in the 2008 object files of the interfaces do not match exactly the symbol in the 2009 symbol file. 2010 @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined. 2011 The library will fail to build if there are symbols in the symbol file that 2012 are not in the exported symbols of the object files of the interfaces. 2013 Additional symbols in the object files are not added to the symbol file. 2014 @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and 2015 must designate an existing file in the object directory. This symbol file 2016 is passed directly to the underlying linker without any symbol processing. 2017 2018 @end itemize 2019 2020@item @b{Library_Reference_Symbol_File} 2021@cindex @code{Library_Reference_Symbol_File} 2022 This attribute may define the path name of a reference symbol file that is 2023 read when the symbol policy is either "compliant" or "controlled", on 2024 platforms that support symbol control, such as VMS, when building a 2025 stand-alone library. The path may be an absolute path or a path relative 2026 to the project directory. 2027 2028@item @b{Library_Symbol_File} 2029@cindex @code{Library_Symbol_File} 2030 This attribute may define the name of the symbol file to be created when 2031 building a stand-alone library when the symbol policy is either "compliant", 2032 "controlled" or "restricted", on platforms that support symbol control, 2033 such as VMS. When symbol policy is "direct", then a file with this name 2034 must exist in the object directory. 2035@end table 2036 2037@c --------------------------------------------- 2038@node Installing a library with project files 2039@subsection Installing a library with project files 2040@c --------------------------------------------- 2041 2042@noindent 2043When using project files, a usable version of the library is created in the 2044directory specified by the @code{Library_Dir} attribute of the library 2045project file. Thus no further action is needed in order to make use of 2046the libraries that are built as part of the general application build. 2047 2048You may want to install a library in a context different from where the library 2049is built. This situation arises with third party suppliers, who may want 2050to distribute a library in binary form where the user is not expected to be 2051able to recompile the library. The simplest option in this case is to provide 2052a project file slightly different from the one used to build the library, by 2053using the @code{externally_built} attribute. @ref{Using Library Projects} 2054 2055Another option is to use @command{gprinstall} to install the library in a 2056different context than the build location. @command{gprinstall} automatically 2057generates a project to use this library, and also copies the minimum set of 2058sources needed to use the library to the install location. 2059@ref{Installation} 2060 2061@c --------------------------------------------- 2062@node Project Extension 2063@section Project Extension 2064@c --------------------------------------------- 2065 2066@noindent 2067During development of a large system, it is sometimes necessary to use 2068modified versions of some of the source files, without changing the original 2069sources. This can be achieved through the @b{project extension} facility. 2070 2071Suppose for instance that our example @code{Build} project is built every night 2072for the whole team, in some shared directory. A developer usually needs to work 2073on a small part of the system, and might not want to have a copy of all the 2074sources and all the object files (mostly because that would require too much 2075disk space, time to recompile everything). He prefers to be able to override 2076some of the source files in his directory, while taking advantage of all the 2077object files generated at night. 2078 2079Another example can be taken from large software systems, where it is common to have 2080multiple implementations of a common interface; in Ada terms, multiple 2081versions of a package body for the same spec. For example, one implementation 2082might be safe for use in tasking programs, while another might be used only 2083in sequential applications. This can be modeled in GNAT using the concept 2084of @emph{project extension}. If one project (the ``child'') @emph{extends} 2085another project (the ``parent'') then by default all source files of the 2086parent project are inherited by the child, but the child project can 2087override any of the parent's source files with new versions, and can also 2088add new files or remove unnecessary ones. 2089This facility is the project analog of a type extension in 2090object-oriented programming. Project hierarchies are permitted (an extending 2091project may itself be extended), and a project that 2092extends a project can also import other projects. 2093 2094A third example is that of using project extensions to provide different 2095versions of the same system. For instance, assume that a @code{Common} 2096project is used by two development branches. One of the branches has now 2097been frozen, and no further change can be done to it or to @code{Common}. 2098However, the other development branch still needs evolution of @code{Common}. 2099Project extensions provide a flexible solution to create a new version 2100of a subsystem while sharing and reusing as much as possible from the original 2101one. 2102 2103A project extension implicitly inherits all the sources and objects from the 2104project it extends. It is possible to create a new version of some of the 2105sources in one of the additional source directories of the extending 2106project. Those new versions hide the original versions. Adding new sources or 2107removing existing ones is also possible. Here is an example on how to extend 2108the project @code{Build} from previous examples: 2109 2110@smallexample @c projectfile 2111 @b{project} Work @b{extends} "../bld/build.gpr" @b{is} 2112 @b{end} Work; 2113@end smallexample 2114 2115@noindent 2116The project after @b{extends} is the one being extended. As usual, it can be 2117specified using an absolute path, or a path relative to any of the directories 2118in the project path (@pxref{Project Dependencies}). This project does not 2119specify source or object directories, so the default values for these 2120attributes will be used that is to say the current directory (where project 2121@code{Work} is placed). We can compile that project with 2122 2123@smallexample 2124 gprbuild -Pwork 2125@end smallexample 2126 2127@noindent 2128If no sources have been placed in the current directory, this command 2129won't do anything, since this project does not change the 2130sources it inherited from @code{Build}, therefore all the object files 2131in @code{Build} and its dependencies are still valid and are reused 2132automatically. 2133 2134Suppose we now want to supply an alternate version of @file{pack.adb} but use 2135the existing versions of @file{pack.ads} and @file{proc.adb}. We can create 2136the new file in Work's current directory (likely by copying the one from the 2137@code{Build} project and making changes to it. If new packages are needed at 2138the same time, we simply create new files in the source directory of the 2139extending project. 2140 2141When we recompile, @command{gprbuild} will now automatically recompile 2142this file (thus creating @file{pack.o} in the current directory) and 2143any file that depends on it (thus creating @file{proc.o}). Finally, the 2144executable is also linked locally. 2145 2146Note that we could have obtained the desired behavior using project import 2147rather than project inheritance. A @code{base} project would contain the 2148sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would 2149import @code{base} and add @file{pack.adb}. In this scenario, @code{base} 2150cannot contain the original version of @file{pack.adb} otherwise there would be 21512 versions of the same unit in the closure of the project and this is not 2152allowed. Generally speaking, it is not recommended to put the spec and the 2153body of a unit in different projects since this affects their autonomy and 2154reusability. 2155 2156In a project file that extends another project, it is possible to 2157indicate that an inherited source is @b{not part} of the sources of the 2158extending project. This is necessary sometimes when a package spec has 2159been overridden and no longer requires a body: in this case, it is 2160necessary to indicate that the inherited body is not part of the sources 2161of the project, otherwise there will be a compilation error 2162when compiling the spec. 2163 2164@cindex @code{Excluded_Source_Files} 2165@cindex @code{Excluded_Source_List_File} 2166For that purpose, the attribute @b{Excluded_Source_Files} is used. 2167Its value is a list of file names. 2168It is also possible to use attribute @code{Excluded_Source_List_File}. 2169Its value is the path of a text file containing one file name per 2170line. 2171 2172@smallexample @c @projectfile 2173project Work extends "../bld/build.gpr" is 2174 for Source_Files use ("pack.ads"); 2175 -- New spec of Pkg does not need a completion 2176 for Excluded_Source_Files use ("pack.adb"); 2177end Work; 2178@end smallexample 2179 2180@noindent 2181All packages that are not declared in the extending project are inherited from 2182the project being extended, with their attributes, with the exception of 2183@code{Linker'Linker_Options} which is never inherited. In particular, an 2184extending project retains all the switches specified in the project being 2185extended. 2186 2187At the project level, if they are not declared in the extending project, some 2188attributes are inherited from the project being extended. They are: 2189@code{Languages}, @code{Main} (for a root non library project) and 2190@code{Library_Name} (for a project extending a library project). 2191 2192@menu 2193* Project Hierarchy Extension:: 2194@end menu 2195 2196@c --------------------------------------------- 2197@node Project Hierarchy Extension 2198@subsection Project Hierarchy Extension 2199@c --------------------------------------------- 2200 2201@noindent 2202One of the fundamental restrictions in project extension is the following: 2203@b{A project is not allowed to import directly or indirectly at the same time an 2204extending project and one of its ancestors}. 2205 2206By means of example, consider the following hierarchy of projects. 2207 2208@smallexample 2209 a.gpr contains package A1 2210 b.gpr, imports a.gpr and contains B1, which depends on A1 2211 c.gpr, imports b.gpr and contains C1, which depends on B1 2212@end smallexample 2213 2214@noindent 2215If we want to locally extend the packages @code{A1} and @code{C1}, we need to 2216create several extending projects: 2217 2218@smallexample 2219 a_ext.gpr which extends a.gpr, and overrides A1 2220 b_ext.gpr which extends b.gpr and imports a_ext.gpr 2221 c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 2222@end smallexample 2223 2224@noindent 2225@smallexample @c projectfile 2226 @b{project} A_Ext @b{extends} "a.gpr" @b{is} 2227 @b{for} Source_Files @b{use} ("a1.adb", "a1.ads"); 2228 @b{end} A_Ext; 2229 2230 @b{with} "a_ext.gpr"; 2231 @b{project} B_Ext @b{extends} "b.gpr" @b{is} 2232 @b{end} B_Ext; 2233 2234 @b{with} "b_ext.gpr"; 2235 @b{project} C_Ext @b{extends} "c.gpr" @b{is} 2236 @b{for} Source_Files @b{use} ("c1.adb"); 2237 @b{end} C_Ext; 2238@end smallexample 2239 2240@noindent 2241The extension @file{b_ext.gpr} is required, even though we are not overriding 2242any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would 2243import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}. 2244 2245@cindex extends all 2246When extending a large system spanning multiple projects, it is often 2247inconvenient to extend every project in the hierarchy that is impacted by a 2248small change introduced in a low layer. In such cases, it is possible to create 2249an @b{implicit extension} of an entire hierarchy using @b{extends all} 2250relationship. 2251 2252When the project is extended using @code{extends all} inheritance, all projects 2253that are imported by it, both directly and indirectly, are considered virtually 2254extended. That is, the project manager creates implicit projects 2255that extend every project in the hierarchy; all these implicit projects do not 2256control sources on their own and use the object directory of 2257the "extending all" project. 2258 2259It is possible to explicitly extend one or more projects in the hierarchy 2260in order to modify the sources. These extending projects must be imported by 2261the "extending all" project, which will replace the corresponding virtual 2262projects with the explicit ones. 2263 2264When building such a project hierarchy extension, the project manager will 2265ensure that both modified sources and sources in implicit extending projects 2266that depend on them are recompiled. 2267 2268Thus, in our example we could create the following projects instead: 2269 2270@smallexample 2271 a_ext.gpr, extends a.gpr and overrides A1 2272 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 2273 2274@end smallexample 2275 2276@noindent 2277@smallexample @c projectfile 2278 @b{project} A_Ext @b{extends} "a.gpr" @b{is} 2279 @b{for} Source_Files @b{use} ("a1.adb", "a1.ads"); 2280 @b{end} A_Ext; 2281 2282 @b{with} "a_ext.gpr"; 2283 @b{project} C_Ext @b{extends} @b{all} "c.gpr" @b{is} 2284 @b{for} Source_Files @b{use} ("c1.adb"); 2285 @b{end} C_Ext; 2286@end smallexample 2287 2288@noindent 2289When building project @file{c_ext.gpr}, the entire modified project space is 2290considered for recompilation, including the sources of @file{b.gpr} that are 2291impacted by the changes in @code{A1} and @code{C1}. 2292 2293@c --------------------------------------------- 2294@node Aggregate Projects 2295@section Aggregate Projects 2296@c --------------------------------------------- 2297 2298@noindent 2299 2300Aggregate projects are an extension of the project paradigm, and are 2301meant to solve a few specific use cases that cannot be solved directly 2302using standard projects. This section will go over a few of these use 2303cases to try to explain what you can use aggregate projects for. 2304 2305@menu 2306* Building all main programs from a single project tree:: 2307* Building a set of projects with a single command:: 2308* Define a build environment:: 2309* Performance improvements in builder:: 2310* Syntax of aggregate projects:: 2311* package Builder in aggregate projects:: 2312@end menu 2313 2314@c ----------------------------------------------------------- 2315@node Building all main programs from a single project tree 2316@subsection Building all main programs from a single project tree 2317@c ----------------------------------------------------------- 2318 2319Most often, an application is organized into modules and submodules, 2320which are very conveniently represented as a project tree or graph 2321(the root project A @code{with}s the projects for each modules (say B and C), 2322which in turn @code{with} projects for submodules. 2323 2324Very often, modules will build their own executables (for testing 2325purposes for instance), or libraries (for easier reuse in various 2326contexts). 2327 2328However, if you build your project through @command{gnatmake} or 2329@command{gprbuild}, using a syntax similar to 2330 2331@smallexample 2332 gprbuild -PA.gpr 2333@end smallexample 2334 2335this will only rebuild the main programs of project A, not those of the 2336imported projects B and C. Therefore you have to spawn several 2337@command{gnatmake} commands, one per project, to build all executables. 2338This is a little inconvenient, but more importantly is inefficient 2339because @command{gnatmake} needs to do duplicate work to ensure that sources are 2340up-to-date, and cannot easily compile things in parallel when using 2341the -j switch. 2342 2343Also libraries are always rebuilt when building a project. 2344 2345You could therefore define an aggregate project Agg that groups A, B 2346and C. Then, when you build with 2347 2348@smallexample 2349 gprbuild -PAgg.gpr 2350@end smallexample 2351 2352this will build all mains from A, B and C. 2353 2354@smallexample @c projectfile 2355 aggregate @b{project} Agg @b{is} 2356 @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); 2357 @b{end} Agg; 2358@end smallexample 2359 2360If B or C do not define any main program (through their Main 2361attribute), all their sources are built. When you do not group them 2362in the aggregate project, only those sources that are needed by A 2363will be built. 2364 2365If you add a main to a project P not already explicitly referenced in the 2366aggregate project, you will need to add "p.gpr" in the list of project 2367files for the aggregate project, or the main will not be built when 2368building the aggregate project. 2369 2370Aggregate projects are supported only with @command{gprbuild}, not with 2371@command{gnatmake}. 2372 2373@c --------------------------------------------------------- 2374@node Building a set of projects with a single command 2375@subsection Building a set of projects with a single command 2376@c --------------------------------------------------------- 2377 2378One other case is when you have multiple applications and libraries 2379that are built independently from each other (but can be built in 2380parallel). For instance, you have a project tree rooted at A, and 2381another one (which might share some subprojects) rooted at B. 2382 2383Using only @command{gprbuild}, you could do 2384 2385@smallexample 2386 gprbuild -PA.gpr 2387 gprbuild -PB.gpr 2388@end smallexample 2389 2390to build both. But again, @command{gprbuild} has to do some duplicate work for 2391those files that are shared between the two, and cannot truly build 2392things in parallel efficiently. 2393 2394If the two projects are really independent, share no sources other 2395than through a common subproject, and have no source files with a 2396common basename, you could create a project C that imports A and 2397B. But these restrictions are often too strong, and one has to build 2398them independently. An aggregate project does not have these 2399limitations and can aggregate two project trees that have common 2400sources. 2401 2402This scenario is particularly useful in environments like VxWorks 653 2403where the applications running in the multiple partitions can be built 2404in parallel through a single @command{gprbuild} command. This also works nicely 2405with Annex E. 2406 2407@c --------------------------------------------- 2408@node Define a build environment 2409@subsection Define a build environment 2410@c --------------------------------------------- 2411 2412The environment variables at the time you launch @command{gprbuild} 2413will influence the view these tools have of the project 2414(PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the 2415projects, environment variables that are referenced in project files 2416through the "external" built-in function, ...). Several command line switches 2417can be used to override those (-X or -aP), but on some systems and 2418with some projects, this might make the command line too long, and on 2419all systems often make it hard to read. 2420 2421An aggregate project can be used to set the environment for all 2422projects built through that aggregate. One of the nice aspects is that 2423you can put the aggregate project under configuration management, and 2424make sure all your user have a consistent environment when 2425building. The syntax looks like 2426 2427@smallexample @c projectfile 2428 aggregate @b{project} Agg @b{is} 2429 @b{for} Project_Files @b{use} ("A.gpr", "B.gpr"); 2430 @b{for} Project_Path @b{use} ("../dir1", "../dir1/dir2"); 2431 @b{for} External ("BUILD") @b{use} "PRODUCTION"; 2432 2433 @b{package} Builder @b{is} 2434 @b{for} Switches ("Ada") @b{use} ("-q"); 2435 @b{end} Builder; 2436 @b{end} Agg; 2437@end smallexample 2438 2439One of the often requested features in projects is to be able to 2440reference external variables in @code{with} declarations, as in 2441 2442@smallexample @c projectfile 2443 @b{with} @b{external}("SETUP") & "path/prj.gpr"; --@i{ ILLEGAL} 2444 @b{project} MyProject @b{is} 2445 ... 2446 @b{end} MyProject; 2447@end smallexample 2448 2449For various reasons, this is not allowed. But using aggregate projects provide 2450an elegant solution. For instance, you could use a project file like: 2451 2452@smallexample @c projectfile 2453aggregate @b{project} Agg @b{is} 2454 @b{for} Project_Path @b{use} (@b{external}("SETUP") & "path"); 2455 @b{for} Project_Files @b{use} ("myproject.gpr"); 2456@b{end} Agg; 2457 2458@b{with} "prj.gpr"; --@i{ searched on Agg'Project_Path} 2459@b{project} MyProject @b{is} 2460 ... 2461@b{end} MyProject; 2462@end smallexample 2463 2464@c -------------------------------------------- 2465@node Performance improvements in builder 2466@subsection Performance improvements in builder 2467@c -------------------------------------------- 2468 2469The loading of aggregate projects is optimized in @command{gprbuild}, 2470so that all files are searched for only once on the disk 2471(thus reducing the number of system calls and contributing to faster 2472compilation times, especially on systems with sources on remote 2473servers). As part of the loading, @command{gprbuild} 2474computes how and where a source file should be compiled, and even if it is 2475found several times in the aggregated projects it will be compiled only 2476once. 2477 2478Since there is no ambiguity as to which switches should be used, files 2479can be compiled in parallel (through the usual -j switch) and this can 2480be done while maximizing the use of CPUs (compared to launching 2481multiple @command{gprbuild} and @command{gnatmake} commands in parallel). 2482 2483@c ------------------------------------- 2484@node Syntax of aggregate projects 2485@subsection Syntax of aggregate projects 2486@c ------------------------------------- 2487 2488An aggregate project follows the general syntax of project files. The 2489recommended extension is still @file{.gpr}. However, a special 2490@code{aggregate} qualifier must be put before the keyword 2491@code{project}. 2492 2493An aggregate project cannot @code{with} any other project (standard or 2494aggregate), except an abstract project which can be used to share attribute 2495values. Also, aggregate projects cannot be extended or imported though a 2496@code{with} clause by any other project. Building other aggregate projects from 2497an aggregate project is done through the Project_Files attribute (see below). 2498 2499An aggregate project does not have any source files directly (only 2500through other standard projects). Therefore a number of the standard 2501attributes and packages are forbidden in an aggregate project. Here is the 2502(non exhaustive) list: 2503 2504@itemize @bullet 2505@item Languages 2506@item Source_Files, Source_List_File and other attributes dealing with 2507 list of sources. 2508@item Source_Dirs, Exec_Dir and Object_Dir 2509@item Library_Dir, Library_Name and other library-related attributes 2510@item Main 2511@item Roots 2512@item Externally_Built 2513@item Inherit_Source_Path 2514@item Excluded_Source_Dirs 2515@item Locally_Removed_Files 2516@item Excluded_Source_Files 2517@item Excluded_Source_List_File 2518@item Interfaces 2519@end itemize 2520 2521The only package that is authorized (albeit optional) is 2522Builder. Other packages (in particular Compiler, Binder and Linker) 2523are forbidden. 2524 2525The following three attributes can be used only in an aggregate project: 2526 2527@table @asis 2528@item @b{Project_Files}: 2529@cindex @code{Project_Files} 2530 2531This attribute is compulsory (or else we are not aggregating any project, 2532and thus not doing anything). It specifies a list of @file{.gpr} files 2533that are grouped in the aggregate. The list may be empty. The project 2534files can be either other aggregate projects, or standard projects. When 2535grouping standard projects, you can have both the root of a project tree 2536(and you do not need to specify all its imported projects), and any project 2537within the tree. 2538 2539Basically, the idea is to specify all those projects that have 2540main programs you want to build and link, or libraries you want to 2541build. You can even specify projects that do not use the Main 2542attribute nor the @code{Library_*} attributes, and the result will be to 2543build all their source files (not just the ones needed by other 2544projects). 2545 2546The file can include paths (absolute or relative). Paths are relative to 2547the location of the aggregate project file itself (if you use a base name, 2548we expect to find the .gpr file in the same directory as the aggregate 2549project file). The environment variables @code{ADA_PROJECT_PATH}, 2550@code{GPR_PROJECT_PATH} and @code{GPR_PROJECT_PATH_FILE} are not used to find 2551the project files. The extension @file{.gpr} is mandatory, since this attribute 2552contains file names, not project names. 2553 2554Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The 2555latter indicates that any subdirectory (recursively) will be 2556searched for matching files. The latter (@code{"**"}) can only occur at the 2557last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but 2558not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent 2559to starting with @code{"./**"}. 2560 2561For now, the pattern @code{"*"} is only allowed in the filename part, not 2562in the directory part. This is mostly for efficiency reasons to limit the 2563number of system calls that are needed. 2564 2565Here are a few valid examples: 2566 2567@smallexample @c projectfile 2568 @b{for} Project_Files @b{use} ("a.gpr", "subdir/b.gpr"); 2569 --@i{ two specific projects relative to the directory of agg.gpr} 2570 2571 @b{for} Project_Files @b{use} ("**/*.gpr"); 2572 --@i{ all projects recursively} 2573@end smallexample 2574 2575@item @b{Project_Path}: 2576@cindex @code{Project_Path} 2577 2578This attribute can be used to specify a list of directories in 2579which to look for project files in @code{with} declarations. 2580 2581When you specify a project in Project_Files (say @code{x/y/a.gpr}), and 2582@code{a.gpr} imports a project @code{b.gpr}, only @code{b.gpr} is searched in 2583the project path. @code{a.gpr} must be exactly at 2584@code{<dir of the aggregate>/x/y/a.gpr}. 2585 2586This attribute, however, does not affect the search for the aggregated 2587project files specified with @code{Project_Files}. 2588 2589Each aggregate project has its own @code{Project_Path} (that is if 2590@code{agg1.gpr} includes @code{agg2.gpr}, they can potentially both have a 2591different @code{Project_Path}). 2592 2593This project path is defined as the concatenation, in that order, of: 2594 2595@itemize @bullet 2596@item the current directory; 2597@item followed by the command line -aP switches; 2598@item then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment 2599variables; 2600@item then the directories from the Project_Path attribute; 2601@item and finally the predefined directories. 2602@end itemize 2603 2604In the example above, agg2.gpr's project path is not influenced by 2605the attribute agg1'Project_Path, nor is agg1 influenced by 2606agg2'Project_Path. 2607 2608This can potentially lead to errors. In the following example: 2609 2610@smallexample 2611 +---------------+ +----------------+ 2612 | Agg1.gpr |-=--includes--=-->| Agg2.gpr | 2613 | 'project_path| | 'project_path | 2614 | | | | 2615 +---------------+ +----------------+ 2616 : : 2617 includes includes 2618 : : 2619 v v 2620 +-------+ +---------+ 2621 | P.gpr |<---------- withs --------| Q.gpr | 2622 +-------+---------\ +---------+ 2623 | | 2624 withs | 2625 | | 2626 v v 2627 +-------+ +---------+ 2628 | R.gpr | | R'.gpr | 2629 +-------+ +---------+ 2630@end smallexample 2631 2632When looking for p.gpr, both aggregates find the same physical file on 2633the disk. However, it might happen that with their different project 2634paths, both aggregate projects would in fact find a different r.gpr. 2635Since we have a common project (p.gpr) "with"ing two different r.gpr, 2636this will be reported as an error by the builder. 2637 2638Directories are relative to the location of the aggregate project file. 2639 2640Example: 2641 2642@smallexample @c projectfile 2643 @b{for} Project_Path @b{use} ("/usr/local/gpr", "gpr/"); 2644@end smallexample 2645 2646@item @b{External}: 2647@cindex @code{External} 2648 2649This attribute can be used to set the value of environment 2650variables as retrieved through the @code{external} function 2651in projects. It does not affect the environment variables 2652themselves (so for instance you cannot use it to change the value 2653of your PATH as seen from the spawned compiler). 2654 2655This attribute affects the external values as seen in the rest of 2656the aggregate project, and in the aggregated projects. 2657 2658The exact value of external a variable comes from one of three 2659sources (each level overrides the previous levels): 2660 2661@itemize @bullet 2662@item An External attribute in aggregate project, for instance 2663 @code{for External ("BUILD_MODE") use "DEBUG"}; 2664 2665@item Environment variables 2666 2667These override the value given by the attribute, so that 2668users can override the value set in the (presumably shared 2669with others team members) aggregate project. 2670 2671@item The -X command line switch to @command{gprbuild} 2672 2673This always takes precedence. 2674 2675@end itemize 2676 2677This attribute is only taken into account in the main aggregate 2678project (i.e. the one specified on the command line to @command{gprbuild}), 2679and ignored in other aggregate projects. It is invalid 2680in standard projects. 2681The goal is to have a consistent value in all 2682projects that are built through the aggregate, which would not 2683be the case in the diamond case: A groups the aggregate 2684projects B and C, which both (either directly or indirectly) 2685build the project P. If B and C could set different values for 2686the environment variables, we would have two different views of 2687P, which in particular might impact the list of source files in P. 2688 2689@end table 2690 2691@c ---------------------------------------------- 2692@node package Builder in aggregate projects 2693@subsection package Builder in aggregate projects 2694@c ---------------------------------------------- 2695 2696As we mentioned before, only the package Builder can be specified in 2697an aggregate project. In this package, only the following attributes 2698are valid: 2699 2700@table @asis 2701@item @b{Switches}: 2702@cindex @code{Switches} 2703This attribute gives the list of switches to use for @command{gprbuild}. 2704Because no mains can be specified for aggregate projects, the only possible 2705index for attribute @code{Switches} is @code{others}. All other indexes will 2706be ignored. 2707 2708Example: 2709 2710@smallexample @c projectfile 2711@b{for} Switches (@b{others}) @b{use} ("-v", "-k", "-j8"); 2712@end smallexample 2713 2714These switches are only read from the main aggregate project (the 2715one passed on the command line), and ignored in all other aggregate 2716projects or projects. 2717 2718It can only contain builder switches, not compiler switches. 2719 2720@item @b{Global_Compilation_Switches} 2721@cindex @code{Global_Compilation_Switches} 2722 2723This attribute gives the list of compiler switches for the various 2724languages. For instance, 2725 2726@smallexample @c projectfile 2727@b{for} Global_Compilation_Switches ("Ada") @b{use} ("O1", "-g"); 2728@b{for} Global_Compilation_Switches ("C") @b{use} ("-O2"); 2729@end smallexample 2730 2731This attribute is only taken into account in the aggregate project 2732specified on the command line, not in other aggregate projects. 2733 2734In the projects grouped by that aggregate, the attribute 2735Builder.Global_Compilation_Switches is also ignored. However, the 2736attribute Compiler.Default_Switches will be taken into account (but 2737that of the aggregate have higher priority). The attribute 2738Compiler.Switches is also taken into account and can be used to 2739override the switches for a specific file. As a result, it always 2740has priority. 2741 2742The rules are meant to avoid ambiguities when compiling. For 2743instance, aggregate project Agg groups the projects A and B, that 2744both depend on C. Here is an extra for all of these projects: 2745 2746@smallexample @c projectfile 2747 aggregate @b{project} Agg @b{is} 2748 @b{for} Project_Files @b{use} ("a.gpr", "b.gpr"); 2749 @b{package} Builder @b{is} 2750 @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-O2"); 2751 @b{end} Builder; 2752 @b{end} Agg; 2753 2754 @b{with} "c.gpr"; 2755 @b{project} A @b{is} 2756 @b{package} Builder @b{is} 2757 @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-O1"); 2758 --@i{ ignored} 2759 @b{end} Builder; 2760 2761 @b{package} Compiler @b{is} 2762 @b{for} Default_Switches ("Ada") 2763 @b{use} ("-O1", "-g"); 2764 @b{for} Switches ("a_file1.adb") 2765 @b{use} ("-O0"); 2766 @b{end} Compiler; 2767 @b{end} A; 2768 2769 @b{with} "c.gpr"; 2770 @b{project} B @b{is} 2771 @b{package} Compiler @b{is} 2772 @b{for} Default_Switches ("Ada") @b{use} ("-O0"); 2773 @b{end} Compiler; 2774 @b{end} B; 2775 2776 @b{project} C @b{is} 2777 @b{package} Compiler @b{is} 2778 @b{for} Default_Switches ("Ada") 2779 @b{use} ("-O3", 2780 "-gnatn"); 2781 @b{for} Switches ("c_file1.adb") 2782 @b{use} ("-O0", "-g"); 2783 @b{end} Compiler; 2784 @b{end} C; 2785@end smallexample 2786 2787then the following switches are used: 2788 2789@itemize @bullet 2790@item all files from project A except a_file1.adb are compiled 2791 with "-O2 -g", since the aggregate project has priority. 2792@item the file a_file1.adb is compiled with 2793 "-O0", since the Compiler.Switches has priority 2794@item all files from project B are compiled with 2795 "-O2", since the aggregate project has priority 2796@item all files from C are compiled with "-O2 -gnatn", except for 2797 c_file1.adb which is compiled with "-O0 -g" 2798@end itemize 2799 2800Even though C is seen through two paths (through A and through 2801B), the switches used by the compiler are unambiguous. 2802 2803@item @b{Global_Configuration_Pragmas} 2804@cindex @code{Global_Configuration_Pragmas} 2805 2806This attribute can be used to specify a file containing 2807configuration pragmas, to be passed to the Ada compiler. Since we 2808ignore the package Builder in other aggregate projects and projects, 2809only those pragmas defined in the main aggregate project will be 2810taken into account. 2811 2812Projects can locally add to those by using the 2813@code{Compiler.Local_Configuration_Pragmas} attribute if they need. 2814 2815@item @b{Global_Config_File} 2816@cindex @code{Global_Config_File} 2817 2818This attribute, indexed with a language name, can be used to specify a config 2819when compiling sources of the language. For Ada, these files are configuration 2820pragmas files. 2821 2822@end table 2823 2824For projects that are built through the aggregate, the package Builder 2825is ignored, except for the Executable attribute which specifies the 2826name of the executables resulting from the link of the main programs, and 2827for the Executable_Suffix. 2828 2829@c --------------------------------------------- 2830@node Aggregate Library Projects 2831@section Aggregate Library Projects 2832@c --------------------------------------------- 2833 2834@noindent 2835 2836Aggregate library projects make it possible to build a single library 2837using object files built using other standard or library 2838projects. This gives the flexibility to describe an application as 2839having multiple modules (a GUI, database access, ...) using different 2840project files (so possibly built with different compiler options) and 2841yet create a single library (static or relocatable) out of the 2842corresponding object files. 2843 2844@menu 2845* Building aggregate library projects:: 2846* Syntax of aggregate library projects:: 2847@end menu 2848 2849@c --------------------------------------------- 2850@node Building aggregate library projects 2851@subsection Building aggregate library projects 2852@c --------------------------------------------- 2853 2854For example, we can define an aggregate project Agg that groups A, B 2855and C: 2856 2857@smallexample @c projectfile 2858 aggregate library @b{project} Agg @b{is} 2859 @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); 2860 @b{for} Library_Name @b{use} ("agg"); 2861 @b{for} Library_Dir @b{use} ("lagg"); 2862 @b{end} Agg; 2863@end smallexample 2864 2865Then, when you build with: 2866 2867@smallexample 2868 gprbuild agg.gpr 2869@end smallexample 2870 2871This will build all units from projects A, B and C and will create a 2872static library named @file{libagg.a} in the @file{lagg} 2873directory. An aggregate library project has the same set of 2874restriction as a standard library project. 2875 2876Note that a shared aggregate library project cannot aggregate a 2877static library project. In platforms where a compiler option is 2878required to create relocatable object files, a Builder package in the 2879aggregate library project may be used: 2880 2881@smallexample @c projectfile 2882 aggregate library @b{project} Agg @b{is} 2883 @b{for} Project_Files @b{use} ("a.gpr", "b.gpr", "c.gpr"); 2884 @b{for} Library_Name @b{use} ("agg"); 2885 @b{for} Library_Dir @b{use} ("lagg"); 2886 @b{for} Library_Kind @b{use} "relocatable"; 2887 2888 @b{package} Builder @b{is} 2889 @b{for} Global_Compilation_Switches ("Ada") @b{use} ("-fPIC"); 2890 @b{end} Builder; 2891 @b{end} Agg; 2892@end smallexample 2893 2894With the above aggregate library Builder package, the @code{-fPIC} 2895option will be passed to the compiler when building any source code 2896from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}. 2897 2898@c --------------------------------------------- 2899@node Syntax of aggregate library projects 2900@subsection Syntax of aggregate library projects 2901@c --------------------------------------------- 2902 2903An aggregate library project follows the general syntax of project 2904files. The recommended extension is still @file{.gpr}. However, a special 2905@code{aggregate library} qualifier must be put before the keyword 2906@code{project}. 2907 2908An aggregate library project cannot @code{with} any other project 2909(standard or aggregate), except an abstract project which can be used 2910to share attribute values. 2911 2912An aggregate library project does not have any source files directly (only 2913through other standard projects). Therefore a number of the standard 2914attributes and packages are forbidden in an aggregate library 2915project. Here is the (non exhaustive) list: 2916 2917@itemize @bullet 2918@item Languages 2919@item Source_Files, Source_List_File and other attributes dealing with 2920 list of sources. 2921@item Source_Dirs, Exec_Dir and Object_Dir 2922@item Main 2923@item Roots 2924@item Externally_Built 2925@item Inherit_Source_Path 2926@item Excluded_Source_Dirs 2927@item Locally_Removed_Files 2928@item Excluded_Source_Files 2929@item Excluded_Source_List_File 2930@item Interfaces 2931@end itemize 2932 2933The only package that is authorized (albeit optional) is Builder. 2934 2935The Project_Files attribute (See @pxref{Aggregate Projects}) is used to 2936described the aggregated projects whose object files have to be 2937included into the aggregate library. The environment variables 2938@code{ADA_PROJECT_PATH}, @code{GPR_PROJECT_PATH} and 2939@code{GPR_PROJECT_PATH_FILE} are not used to find the project files. 2940 2941@c --------------------------------------------- 2942@node Project File Reference 2943@section Project File Reference 2944@c --------------------------------------------- 2945 2946@noindent 2947This section describes the syntactic structure of project files, the various 2948constructs that can be used. Finally, it ends with a summary of all available 2949attributes. 2950 2951@menu 2952* Project Declaration:: 2953* Qualified Projects:: 2954* Declarations:: 2955* Packages:: 2956* Expressions:: 2957* External Values:: 2958* Typed String Declaration:: 2959* Variables:: 2960* Case Constructions:: 2961* Attributes:: 2962@end menu 2963 2964@c --------------------------------------------- 2965@node Project Declaration 2966@subsection Project Declaration 2967@c --------------------------------------------- 2968 2969@noindent 2970Project files have an Ada-like syntax. The minimal project file is: 2971 2972@smallexample @c projectfile 2973@group 2974@b{project} Empty @b{is} 2975@b{end} Empty; 2976@end group 2977@end smallexample 2978 2979@noindent 2980The identifier @code{Empty} is the name of the project. 2981This project name must be present after the reserved 2982word @code{end} at the end of the project file, followed by a semi-colon. 2983 2984@b{Identifiers} (i.e.@: the user-defined names such as project or variable names) 2985have the same syntax as Ada identifiers: they must start with a letter, 2986and be followed by zero or more letters, digits or underscore characters; 2987it is also illegal to have two underscores next to each other. Identifiers 2988are always case-insensitive ("Name" is the same as "name"). 2989 2990@smallexample 2991simple_name ::= identifier 2992name ::= simple_name @{ . simple_name @} 2993@end smallexample 2994 2995@noindent 2996@b{Strings} are used for values of attributes or as indexes for these 2997attributes. They are in general case sensitive, except when noted 2998otherwise (in particular, strings representing file names will be case 2999insensitive on some systems, so that "file.adb" and "File.adb" both 3000represent the same file). 3001 3002@b{Reserved words} are the same as for standard Ada 95, and cannot 3003be used for identifiers. In particular, the following words are currently 3004used in project files, but others could be added later on. In bold are the 3005extra reserved words in project files: @code{all, at, case, end, for, is, 3006limited, null, others, package, renames, type, use, when, with, @b{extends}, 3007@b{external}, @b{project}}. 3008 3009@b{Comments} in project files have the same syntax as in Ada, two consecutive 3010hyphens through the end of the line. 3011 3012A project may be an @b{independent project}, entirely defined by a single 3013project file. Any source file in an independent project depends only 3014on the predefined library and other source files in the same project. 3015But a project may also depend on other projects, either by importing them 3016through @b{with clauses}, or by @b{extending} at most one other project. Both 3017types of dependency can be used in the same project. 3018 3019A path name denotes a project file. It can be absolute or relative. 3020An absolute path name includes a sequence of directories, in the syntax of 3021the host operating system, that identifies uniquely the project file in the 3022file system. A relative path name identifies the project file, relative 3023to the directory that contains the current project, or relative to a 3024directory listed in the environment variables ADA_PROJECT_PATH and 3025GPR_PROJECT_PATH. Path names are case sensitive if file names in the host 3026operating system are case sensitive. As a special case, the directory 3027separator can always be "/" even on Windows systems, so that project files 3028can be made portable across architectures. 3029The syntax of the environment variables ADA_PROJECT_PATH and 3030GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and 3031semicolons on Windows. 3032 3033A given project name can appear only once in a context clause. 3034 3035It is illegal for a project imported by a context clause to refer, directly 3036or indirectly, to the project in which this context clause appears (the 3037dependency graph cannot contain cycles), except when one of the with clauses 3038in the cycle is a @b{limited with}. 3039@c ??? Need more details here 3040 3041@smallexample @c projectfile 3042@b{with} "other_project.gpr"; 3043@b{project} My_Project @b{extends} "extended.gpr" @b{is} 3044@b{end} My_Project; 3045@end smallexample 3046 3047@noindent 3048These dependencies form a @b{directed graph}, potentially cyclic when using 3049@b{limited with}. The subgraph reflecting the @b{extends} relations is a tree. 3050 3051A project's @b{immediate sources} are the source files directly defined by 3052that project, either implicitly by residing in the project source directories, 3053or explicitly through any of the source-related attributes. 3054More generally, a project's @b{sources} are the immediate sources of the 3055project together with the immediate sources (unless overridden) of any project 3056on which it depends directly or indirectly. 3057 3058A @b{project hierarchy} can be created, where projects are children of 3059other projects. The name of such a child project must be @code{Parent.Child}, 3060where @code{Parent} is the name of the parent project. In particular, this 3061makes all @code{with} clauses of the parent project automatically visible 3062in the child project. 3063 3064@smallexample 3065project ::= context_clause project_declaration 3066 3067context_clause ::= @{with_clause@} 3068with_clause ::= @i{with} path_name @{ , path_name @} ; 3069path_name ::= string_literal 3070 3071project_declaration ::= simple_project_declaration | project_extension 3072simple_project_declaration ::= 3073 @i{project} @i{<project_>}name @i{is} 3074 @{declarative_item@} 3075 @i{end} <project_>simple_name; 3076@end smallexample 3077 3078@c --------------------------------------------- 3079@node Qualified Projects 3080@subsection Qualified Projects 3081@c --------------------------------------------- 3082 3083@noindent 3084Before the reserved @code{project}, there may be one or two @b{qualifiers}, that 3085is identifiers or reserved words, to qualify the project. 3086The current list of qualifiers is: 3087 3088@table @asis 3089@item @b{abstract}: qualifies a project with no sources. Such a 3090 project must either have no declaration of attributes @code{Source_Dirs}, 3091 @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of 3092 @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared 3093 as empty. If it extends another project, the project it extends must also be a 3094 qualified abstract project. 3095@item @b{standard}: a standard project is a non library project with sources. 3096 This is the default (implicit) qualifier. 3097@item @b{aggregate}: a project whose sources are aggregated from other 3098project files. 3099@item @b{aggregate library}: a library whose sources are aggregated 3100from other project or library project files. 3101@item @b{library}: a library project must declare both attributes 3102 @code{Library_Name} and @code{Library_Dir}. 3103@item @b{configuration}: a configuration project cannot be in a project tree. 3104 It describes compilers and other tools to @command{gprbuild}. 3105@end table 3106 3107@c --------------------------------------------- 3108@node Declarations 3109@subsection Declarations 3110@c --------------------------------------------- 3111 3112@noindent 3113Declarations introduce new entities that denote types, variables, attributes, 3114and packages. Some declarations can only appear immediately within a project 3115declaration. Others can appear within a project or within a package. 3116 3117@smallexample 3118declarative_item ::= simple_declarative_item 3119 | typed_string_declaration 3120 | package_declaration 3121 3122simple_declarative_item ::= variable_declaration 3123 | typed_variable_declaration 3124 | attribute_declaration 3125 | case_construction 3126 | empty_declaration 3127 3128empty_declaration ::= @i{null} ; 3129@end smallexample 3130 3131@noindent 3132An empty declaration is allowed anywhere a declaration is allowed. It has 3133no effect. 3134 3135@c --------------------------------------------- 3136@node Packages 3137@subsection Packages 3138@c --------------------------------------------- 3139 3140@noindent 3141A project file may contain @b{packages}, that group attributes (typically 3142all the attributes that are used by one of the GNAT tools). 3143 3144A package with a given name may only appear once in a project file. 3145The following packages are currently supported in project files 3146(See @pxref{Attributes} for the list of attributes that each can contain). 3147 3148@table @code 3149@item Binder 3150 This package specifies characteristics useful when invoking the binder either 3151 directly via the @command{gnat} driver or when using a builder such as 3152 @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}. 3153@item Builder 3154 This package specifies the compilation options used when building an 3155 executable or a library for a project. Most of the options should be 3156 set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages, 3157 but there are some general options that should be defined in this 3158 package. @xref{Main Subprograms}, and @pxref{Executable File Names} in 3159 particular. 3160@ifclear FSFEDITION 3161@item Check 3162 This package specifies the options used when calling the checking tool 3163 @command{gnatcheck} via the @command{gnat} driver. Its attribute 3164 @b{Default_Switches} has the same semantics as for the package 3165 @code{Builder}. The first string should always be @code{-rules} to specify 3166 that all the other options belong to the @code{-rules} section of the 3167 parameters to @command{gnatcheck}. 3168@end ifclear 3169@item Clean 3170 This package specifies the options used when cleaning a project or a project 3171 tree using the tools @command{gnatclean} or @command{gprclean}. 3172@item Compiler 3173 This package specifies the compilation options used by the compiler for 3174 each languages. @xref{Tools Options in Project Files}. 3175@item Cross_Reference 3176 This package specifies the options used when calling the library tool 3177 @command{gnatxref} via the @command{gnat} driver. Its attributes 3178 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3179 package @code{Builder}. 3180@ifclear FSFEDITION 3181@item Eliminate 3182 This package specifies the options used when calling the tool 3183 @command{gnatelim} via the @command{gnat} driver. Its attributes 3184 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3185 package @code{Builder}. 3186@end ifclear 3187@item Finder 3188 This package specifies the options used when calling the search tool 3189 @command{gnatfind} via the @command{gnat} driver. Its attributes 3190 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3191 package @code{Builder}. 3192@item Gnatls 3193 This package specifies the options to use when invoking @command{gnatls} 3194 via the @command{gnat} driver. 3195@ifclear FSFEDITION 3196@item Gnatstub 3197 This package specifies the options used when calling the tool 3198 @command{gnatstub} via the @command{gnat} driver. Its attributes 3199 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3200 package @code{Builder}. 3201@end ifclear 3202@item IDE 3203 This package specifies the options used when starting an integrated 3204 development environment, for instance @command{GPS} or @command{Gnatbench}. 3205@item Install 3206 This package specifies the options used when installing a project 3207 with @command{gprinstall}. @xref{Installation}. 3208@item Linker 3209 This package specifies the options used by the linker. 3210 @xref{Main Subprograms}. 3211@ifclear FSFEDITION 3212@item Metrics 3213 This package specifies the options used when calling the tool 3214 @command{gnatmetric} via the @command{gnat} driver. Its attributes 3215 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3216 package @code{Builder}. 3217@end ifclear 3218@item Naming 3219 This package specifies the naming conventions that apply 3220 to the source files in a project. In particular, these conventions are 3221 used to automatically find all source files in the source directories, 3222 or given a file name to find out its language for proper processing. 3223 @xref{Naming Schemes}. 3224@ifclear FSFEDITION 3225@item Pretty_Printer 3226 This package specifies the options used when calling the formatting tool 3227 @command{gnatpp} via the @command{gnat} driver. Its attributes 3228 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3229 package @code{Builder}. 3230@end ifclear 3231@item Remote 3232 This package is used by @command{gprbuild} to describe how distributed 3233 compilation should be done. 3234@item Stack 3235 This package specifies the options used when calling the tool 3236 @command{gnatstack} via the @command{gnat} driver. Its attributes 3237 @b{Default_Switches} and @b{Switches} have the same semantics as for the 3238 package @code{Builder}. 3239@item Synchronize 3240 This package specifies the options used when calling the tool 3241 @command{gnatsync} via the @command{gnat} driver. 3242 3243@end table 3244 3245In its simplest form, a package may be empty: 3246 3247@smallexample @c projectfile 3248@group 3249@b{project} Simple @b{is} 3250 @b{package} Builder @b{is} 3251 @b{end} Builder; 3252@b{end} Simple; 3253@end group 3254@end smallexample 3255 3256@noindent 3257A package may contain @b{attribute declarations}, 3258@b{variable declarations} and @b{case constructions}, as will be 3259described below. 3260 3261When there is ambiguity between a project name and a package name, 3262the name always designates the project. To avoid possible confusion, it is 3263always a good idea to avoid naming a project with one of the 3264names allowed for packages or any name that starts with @code{gnat}. 3265 3266A package can also be defined by a @b{renaming declaration}. The new package 3267renames a package declared in a different project file, and has the same 3268attributes as the package it renames. The name of the renamed package 3269must be the same as the name of the renaming package. The project must 3270contain a package declaration with this name, and the project 3271must appear in the context clause of the current project, or be its parent 3272project. It is not possible to add or override attributes to the renaming 3273project. If you need to do so, you should use an @b{extending declaration} 3274(see below). 3275 3276Packages that are renamed in other project files often come from project files 3277that have no sources: they are just used as templates. Any modification in the 3278template will be reflected automatically in all the project files that rename 3279a package from the template. This is a very common way to share settings 3280between projects. 3281 3282Finally, a package can also be defined by an @b{extending declaration}. This is 3283similar to a @b{renaming declaration}, except that it is possible to add or 3284override attributes. 3285 3286@smallexample 3287package_declaration ::= package_spec | package_renaming | package_extension 3288package_spec ::= 3289 @i{package} @i{<package_>}simple_name @i{is} 3290 @{simple_declarative_item@} 3291 @i{end} package_identifier ; 3292package_renaming ::== 3293 @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ; 3294package_extension ::== 3295 @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is} 3296 @{simple_declarative_item@} 3297 @i{end} package_identifier ; 3298@end smallexample 3299 3300@c --------------------------------------------- 3301@node Expressions 3302@subsection Expressions 3303@c --------------------------------------------- 3304 3305@noindent 3306An expression is any value that can be assigned to an attribute or a 3307variable. It is either a literal value, or a construct requiring runtime 3308computation by the project manager. In a project file, the computed value of 3309an expression is either a string or a list of strings. 3310 3311A string value is one of: 3312@itemize @bullet 3313@item A literal string, for instance @code{"comm/my_proj.gpr"} 3314@item The name of a variable that evaluates to a string (@pxref{Variables}) 3315@item The name of an attribute that evaluates to a string (@pxref{Attributes}) 3316@item An external reference (@pxref{External Values}) 3317@item A concatenation of the above, as in @code{"prefix_" & Var}. 3318 3319@end itemize 3320 3321@noindent 3322A list of strings is one of the following: 3323 3324@itemize @bullet 3325@item A parenthesized comma-separated list of zero or more string expressions, for 3326 instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}. 3327@item The name of a variable that evaluates to a list of strings 3328@item The name of an attribute that evaluates to a list of strings 3329@item A concatenation of a list of strings and a string (as defined above), for 3330 instance @code{("A", "B") & "C"} 3331@item A concatenation of two lists of strings 3332 3333@end itemize 3334 3335@noindent 3336The following is the grammar for expressions 3337 3338@smallexample 3339string_literal ::= "@{string_element@}" -- Same as Ada 3340string_expression ::= string_literal 3341 | @i{variable_}name 3342 | external_value 3343 | attribute_reference 3344 | ( string_expression @{ & string_expression @} ) 3345string_list ::= ( string_expression @{ , string_expression @} ) 3346 | @i{string_variable}_name 3347 | @i{string_}attribute_reference 3348term ::= string_expression | string_list 3349expression ::= term @{ & term @} -- Concatenation 3350@end smallexample 3351 3352@noindent 3353Concatenation involves strings and list of strings. As soon as a list of 3354strings is involved, the result of the concatenation is a list of strings. The 3355following Ada declarations show the existing operators: 3356 3357@smallexample @c ada 3358 @b{function} "&" (X : String; Y : String) @b{return} String; 3359 @b{function} "&" (X : String_List; Y : String) @b{return} String_List; 3360 @b{function} "&" (X : String_List; Y : String_List) @b{return} String_List; 3361@end smallexample 3362 3363@noindent 3364Here are some specific examples: 3365 3366@smallexample @c projectfile 3367@group 3368 List := () & File_Name; --@i{ One string in this list} 3369 List2 := List & (File_Name & ".orig"); --@i{ Two strings} 3370 Big_List := List & Lists2; --@i{ Three strings} 3371 Illegal := "gnat.adc" & List2; --@i{ Illegal, must start with list} 3372@end group 3373@end smallexample 3374 3375@c --------------------------------------------- 3376@node External Values 3377@subsection External Values 3378@c --------------------------------------------- 3379 3380@noindent 3381An external value is an expression whose value is obtained from the command 3382that invoked the processing of the current project file (typically a 3383@command{gnatmake} or @command{gprbuild} command). 3384 3385There are two kinds of external values, one that returns a single string, and 3386one that returns a string list. 3387 3388The syntax of a single string external value is: 3389 3390@smallexample 3391external_value ::= @i{external} ( string_literal [, string_literal] ) 3392@end smallexample 3393 3394@noindent 3395The first string_literal is the string to be used on the command line or 3396in the environment to specify the external value. The second string_literal, 3397if present, is the default to use if there is no specification for this 3398external value either on the command line or in the environment. 3399 3400Typically, the external value will either exist in the 3401environment variables 3402or be specified on the command line through the 3403@option{-X@emph{vbl}=@emph{value}} switch. If both 3404are specified, then the command line value is used, so that a user can more 3405easily override the value. 3406 3407The function @code{external} always returns a string. It is an error if the 3408value was not found in the environment and no default was specified in the 3409call to @code{external}. 3410 3411An external reference may be part of a string expression or of a string 3412list expression, and can therefore appear in a variable declaration or 3413an attribute declaration. 3414 3415Most of the time, this construct is used to initialize typed variables, which 3416are then used in @b{case} constructions to control the value assigned to 3417attributes in various scenarios. Thus such variables are often called 3418@b{scenario variables}. 3419 3420The syntax for a string list external value is: 3421 3422@smallexample 3423external_value ::= @i{external_as_list} ( string_literal , string_literal ) 3424@end smallexample 3425 3426@noindent 3427The first string_literal is the string to be used on the command line or 3428in the environment to specify the external value. The second string_literal is 3429the separator between each component of the string list. 3430 3431If the external value does not exist in the environment or on the command line, 3432the result is an empty list. This is also the case, if the separator is an 3433empty string or if the external value is only one separator. 3434 3435Any separator at the beginning or at the end of the external value is 3436discarded. Then, if there is no separator in the external value, the result is 3437a string list with only one string. Otherwise, any string between the beginning 3438and the first separator, between two consecutive separators and between the 3439last separator and the end are components of the string list. 3440 3441@smallexample 3442 @i{external_as_list} ("SWITCHES", ",") 3443@end smallexample 3444 3445@noindent 3446If the external value is "-O2,-g", 3447the result is ("-O2", "-g"). 3448 3449If the external value is ",-O2,-g,", 3450the result is also ("-O2", "-g"). 3451 3452if the external value is "-gnatv", 3453the result is ("-gnatv"). 3454 3455If the external value is ",,", the result is (""). 3456 3457If the external value is ",", the result is (), the empty string list. 3458 3459@c --------------------------------------------- 3460@node Typed String Declaration 3461@subsection Typed String Declaration 3462@c --------------------------------------------- 3463 3464@noindent 3465A @b{type declaration} introduces a discrete set of string literals. 3466If a string variable is declared to have this type, its value 3467is restricted to the given set of literals. These are the only named 3468types in project files. A string type may only be declared at the project 3469level, not inside a package. 3470 3471@smallexample 3472typed_string_declaration ::= 3473 @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} ); 3474@end smallexample 3475 3476@noindent 3477The string literals in the list are case sensitive and must all be different. 3478They may include any graphic characters allowed in Ada, including spaces. 3479Here is an example of a string type declaration: 3480 3481@smallexample @c projectfile 3482 @b{type} OS @b{is} ("NT", "nt", "Unix", "GNU/Linux", "other OS"); 3483@end smallexample 3484 3485@noindent 3486Variables of a string type are called @b{typed variables}; all other 3487variables are called @b{untyped variables}. Typed variables are 3488particularly useful in @code{case} constructions, to support conditional 3489attribute declarations. (@pxref{Case Constructions}). 3490 3491A string type may be referenced by its name if it has been declared in the same 3492project file, or by an expanded name whose prefix is the name of the project 3493in which it is declared. 3494 3495@c --------------------------------------------- 3496@node Variables 3497@subsection Variables 3498@c --------------------------------------------- 3499 3500@noindent 3501@b{Variables} store values (strings or list of strings) and can appear 3502as part of an expression. The declaration of a variable creates the 3503variable and assigns the value of the expression to it. The name of the 3504variable is available immediately after the assignment symbol, if you 3505need to reuse its old value to compute the new value. Before the completion 3506of its first declaration, the value of a variable defaults to the empty 3507string (""). 3508 3509A @b{typed} variable can be used as part of a @b{case} expression to 3510compute the value, but it can only be declared once in the project file, 3511so that all case constructions see the same value for the variable. This 3512provides more consistency and makes the project easier to understand. 3513The syntax for its declaration is identical to the Ada syntax for an 3514object declaration. In effect, a typed variable acts as a constant. 3515 3516An @b{untyped} variable can be declared and overridden multiple times 3517within the same project. It is declared implicitly through an Ada 3518assignment. The first declaration establishes the kind of the variable 3519(string or list of strings) and successive declarations must respect 3520the initial kind. Assignments are executed in the order in which they 3521appear, so the new value replaces the old one and any subsequent reference 3522to the variable uses the new value. 3523 3524A variable may be declared at the project file level, or within a package. 3525 3526@smallexample 3527typed_variable_declaration ::= 3528 @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression; 3529variable_declaration ::= @i{<variable_>}simple_name := expression; 3530@end smallexample 3531 3532@noindent 3533Here are some examples of variable declarations: 3534 3535@smallexample @c projectfile 3536@group 3537 This_OS : OS := @b{external} ("OS"); --@i{ a typed variable declaration} 3538 That_OS := "GNU/Linux"; --@i{ an untyped variable declaration} 3539 3540 Name := "readme.txt"; 3541 Save_Name := Name & ".saved"; 3542 3543 Empty_List := (); 3544 List_With_One_Element := ("-gnaty"); 3545 List_With_Two_Elements := List_With_One_Element & "-gnatg"; 3546 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"); 3547@end group 3548@end smallexample 3549 3550@noindent 3551A @b{variable reference} may take several forms: 3552 3553@itemize @bullet 3554@item The simple variable name, for a variable in the current package (if any) 3555 or in the current project 3556@item An expanded name, whose prefix is a context name. 3557 3558@end itemize 3559 3560@noindent 3561A @b{context} may be one of the following: 3562 3563@itemize @bullet 3564@item The name of an existing package in the current project 3565@item The name of an imported project of the current project 3566@item The name of an ancestor project (i.e., a project extended by the current 3567 project, either directly or indirectly) 3568@item An expanded name whose prefix is an imported/parent project name, and 3569 whose selector is a package name in that project. 3570@end itemize 3571 3572@c --------------------------------------------- 3573@node Case Constructions 3574@subsection Case Constructions 3575@c --------------------------------------------- 3576 3577@noindent 3578A @b{case} construction is used in a project file to effect conditional 3579behavior. Through this construction, you can set the value of attributes 3580and variables depending on the value previously assigned to a typed 3581variable. 3582 3583All choices in a choice list must be distinct. Unlike Ada, the choice 3584lists of all alternatives do not need to include all values of the type. 3585An @code{others} choice must appear last in the list of alternatives. 3586 3587The syntax of a @code{case} construction is based on the Ada case construction 3588(although the @code{null} declaration for empty alternatives is optional). 3589 3590The case expression must be a string variable, either typed or not, whose value 3591is often given by an external reference (@pxref{External Values}). 3592 3593Each alternative starts with the reserved word @code{when}, either a list of 3594literal strings separated by the @code{"|"} character or the reserved word 3595@code{others}, and the @code{"=>"} token. 3596When the case expression is a typed string variable, each literal string must 3597belong to the string type that is the type of the case variable. 3598After each @code{=>}, there are zero or more declarations. The only 3599declarations allowed in a case construction are other case constructions, 3600attribute declarations and variable declarations. String type declarations and 3601package declarations are not allowed. Variable declarations are restricted to 3602variables that have already been declared before the case construction. 3603 3604@smallexample 3605case_construction ::= 3606 @i{case} @i{<variable_>}name @i{is} @{case_item@} @i{end case} ; 3607 3608case_item ::= 3609 @i{when} discrete_choice_list => 3610 @{case_declaration 3611 | attribute_declaration 3612 | variable_declaration 3613 | empty_declaration@} 3614 3615discrete_choice_list ::= string_literal @{| string_literal@} | @i{others} 3616@end smallexample 3617 3618@noindent 3619Here is a typical example, with a typed string variable: 3620 3621@smallexample @c projectfile 3622@group 3623@b{project} MyProj @b{is} 3624 @b{type} OS_Type @b{is} ("GNU/Linux", "Unix", "NT", "VMS"); 3625 OS : OS_Type := @b{external} ("OS", "GNU/Linux"); 3626 3627 @b{package} Compiler @b{is} 3628 @b{case} OS @b{is} 3629 @b{when} "GNU/Linux" | "Unix" => 3630 @b{for} Switches ("Ada") 3631 @b{use} ("-gnath"); 3632 @b{when} "NT" => 3633 @b{for} Switches ("Ada") 3634 @b{use} ("-gnatP"); 3635 @b{when} @b{others} => 3636 @b{null}; 3637 @b{end} @b{case}; 3638 @b{end} Compiler; 3639@b{end} MyProj; 3640@end group 3641@end smallexample 3642 3643@c --------------------------------------------- 3644@node Attributes 3645@subsection Attributes 3646@c --------------------------------------------- 3647 3648@menu 3649* Project Level Attributes:: 3650* Package Binder Attributes:: 3651* Package Builder Attributes:: 3652@ifclear FSFEDITION 3653* Package Check Attributes:: 3654@end ifclear 3655* Package Clean Attributes:: 3656* Package Compiler Attributes:: 3657* Package Cross_Reference Attributes:: 3658@ifclear FSFEDITION 3659* Package Eliminate Attributes:: 3660@end ifclear 3661* Package Finder Attributes:: 3662* Package gnatls Attributes:: 3663@ifclear FSFEDITION 3664* Package gnatstub Attributes:: 3665@end ifclear 3666* Package IDE Attributes:: 3667* Package Install Attributes:: 3668* Package Linker Attributes:: 3669@ifclear FSFEDITION 3670* Package Metrics Attribute:: 3671@end ifclear 3672* Package Naming Attributes:: 3673@ifclear FSFEDITION 3674* Package Pretty_Printer Attributes:: 3675@end ifclear 3676* Package Remote Attributes:: 3677* Package Stack Attributes:: 3678* Package Synchronize Attributes:: 3679@end menu 3680 3681@noindent 3682A project (and its packages) may have @b{attributes} that define 3683the project's properties. Some attributes have values that are strings; 3684others have values that are string lists. 3685 3686@smallexample 3687attribute_declaration ::= 3688 simple_attribute_declaration | indexed_attribute_declaration 3689simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ; 3690indexed_attribute_declaration ::= 3691 @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ; 3692attribute_designator ::= 3693 @i{<simple_attribute_>}simple_name 3694 | @i{<indexed_attribute_>}simple_name ( string_literal ) 3695@end smallexample 3696 3697@noindent 3698There are two categories of attributes: @b{simple attributes} 3699and @b{indexed attributes}. 3700Each simple attribute has a default value: the empty string (for string 3701attributes) and the empty list (for string list attributes). 3702An attribute declaration defines a new value for an attribute, and overrides 3703the previous value. The syntax of a simple attribute declaration is similar to 3704that of an attribute definition clause in Ada. 3705 3706Some attributes are indexed. These attributes are mappings whose 3707domain is a set of strings. They are declared one association 3708at a time, by specifying a point in the domain and the corresponding image 3709of the attribute. 3710Like untyped variables and simple attributes, indexed attributes 3711may be declared several times. Each declaration supplies a new value for the 3712attribute, and replaces the previous setting. 3713 3714Here are some examples of attribute declarations: 3715 3716@smallexample @c projectfile 3717 --@i{ simple attributes} 3718 @b{for} Object_Dir @b{use} "objects"; 3719 @b{for} Source_Dirs @b{use} ("units", "test/drivers"); 3720 3721 --@i{ indexed attributes} 3722 @b{for} Body ("main") @b{use} "Main.ada"; 3723 @b{for} Switches ("main.ada") 3724 @b{use} ("-v", "-gnatv"); 3725 @b{for} Switches ("main.ada") @b{use} Builder'Switches ("main.ada") & "-g"; 3726 3727 --@i{ indexed attributes copy (from package Builder in project Default)} 3728 --@i{ The package name must always be specified, even if it is the current} 3729 --@i{ package.} 3730 @b{for} Default_Switches @b{use} Default.Builder'Default_Switches; 3731@end smallexample 3732 3733@noindent 3734Attributes references may appear anywhere in expressions, and are used 3735to retrieve the value previously assigned to the attribute. If an attribute 3736has not been set in a given package or project, its value defaults to the 3737empty string or the empty list, with some exceptions. 3738 3739@smallexample 3740attribute_reference ::= 3741 attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ] 3742attribute_prefix ::= @i{project} 3743 | @i{<project_>}simple_name 3744 | package_identifier 3745 | @i{<project_>}simple_name . package_identifier 3746@end smallexample 3747 3748@noindent 3749Examples are: 3750 3751@smallexample @c projectfile 3752 @b{project}'Object_Dir 3753 Naming'Dot_Replacement 3754 Imported_Project'Source_Dirs 3755 Imported_Project.Naming'Casing 3756 Builder'Default_Switches ("Ada") 3757@end smallexample 3758 3759The exceptions to the empty defaults are: 3760 3761@itemize @bullet 3762@item Object_Dir: default is "." 3763@item Exec_Dir: default is 'Object_Dir, that is the value of attribute 3764 Object_Dir in the same project, declared or defaulted. 3765@item Source_Dirs: default is (".") 3766@end itemize 3767 3768@noindent 3769The prefix of an attribute may be: 3770 3771@itemize @bullet 3772@item @code{project} for an attribute of the current project 3773@item The name of an existing package of the current project 3774@item The name of an imported project 3775@item The name of a parent project that is extended by the current project 3776@item An expanded name whose prefix is imported/parent project name, 3777 and whose selector is a package name 3778 3779@end itemize 3780 3781@noindent 3782 3783In the following sections, all predefined attributes are succinctly described, 3784first the project level attributes, that is those attributes that are not in a 3785package, then the attributes in the different packages. 3786 3787It is possible for different tools to dynamically create new packages with 3788attributes, or new attributes in predefined packages. These attributes are 3789not documented here. 3790 3791The attributes under Configuration headings are usually found only in 3792configuration project files. 3793 3794The characteristics of each attribute are indicated as follows: 3795 3796@itemize @bullet 3797 3798@item @b{Type of value} 3799 3800The value of an attribute may be a single string, indicated by the word 3801"single", or a string list, indicated by the word "list". 3802 3803@item @b{Read-only} 3804 3805When the attribute is read-only, that is when it is not allowed to declare 3806the attribute, this is indicated by the words "read-only". 3807 3808@item @b{Optional index} 3809 3810If it is allowed in the value of the attribute (both single and list) to have 3811an optional index, this is indicated by the words "optional index". 3812 3813@item @b{Indexed attribute} 3814 3815When an it is an indexed attribute, this is indicated by the word "indexed". 3816 3817@item @b{Case-sensitivity of the index} 3818 3819For an indexed attribute, if the index is case-insensitive, this is indicated 3820by the words "case-insensitive index". 3821 3822@item @b{File name index} 3823 3824For an indexed attribute, when the index is a file name, this is indicated by 3825the words "file name index". The index may or may not be case-sensitive, 3826depending on the platform. 3827 3828@item @b{others allowed in index} 3829 3830For an indexed attribute, if it is allowed to use @b{others} as the index, 3831this is indicated by the words "others allowed". 3832 3833When @b{others} is used as the index of an indexed attribute, the value of 3834the attribute indexed by @b{others} is used when no other index would apply. 3835 3836@end itemize 3837 3838@node Project Level Attributes 3839@subsubsection Project Level Attributes 3840@noindent 3841 3842@itemize @bullet 3843 3844@item @b{General} 3845 3846@itemize @bullet 3847 3848@item @b{Name}: single, read-only 3849 3850The name of the project. 3851 3852@item @b{Project_Dir}: single, read-only 3853 3854The path name of the project directory. 3855 3856@item @b{Main}: list, optional index 3857 3858The list of main sources for the executables. 3859 3860@item @b{Languages}: list 3861 3862The list of languages of the sources of the project. 3863 3864@item @b{Roots}: list, indexed, file name index 3865 3866The index is the file name of an executable source. Indicates the list of units 3867from the main project that need to be bound and linked with their closures 3868with the executable. The index is either a file name, a language name or "*". 3869The roots for an executable source are those in @b{Roots} with an index that 3870is the executable source file name, if declared. Otherwise, they are those in 3871@b{Roots} with an index that is the language name of the executable source, 3872if present. Otherwise, they are those in @b{Roots ("*")}, if declared. If none 3873of these three possibilities are declared, then there are no roots for the 3874executable source. 3875 3876@item @b{Externally_Built}: single 3877 3878Indicates if the project is externally built. 3879Only case-insensitive values allowed are "true" and "false", the default. 3880 3881@end itemize 3882@noindent 3883 3884@item @b{Directories} 3885 3886@itemize @bullet 3887 3888@item @b{Object_Dir}: single 3889 3890Indicates the object directory for the project. 3891 3892@item @b{Exec_Dir}: single 3893 3894Indicates the exec directory for the project, that is the directory where the 3895executables are. 3896 3897@item @b{Source_Dirs}: list 3898 3899The list of source directories of the project. 3900 3901@item @b{Inherit_Source_Path}: list, indexed, case-insensitive index 3902 3903Index is a language name. Value is a list of language names. Indicates that 3904in the source search path of the index language the source directories of 3905the languages in the list should be included. 3906 3907Example: 3908 3909for Inherit_Source_Path ("C++") use ("C"); 3910 3911@item @b{Exclude_Source_Dirs}: list 3912 3913The list of directories that are included in Source_Dirs but are not source 3914directories of the project. 3915 3916@item @b{Ignore_Source_Sub_Dirs}: list 3917 3918Value is a list of simple names for subdirectories that are removed from the 3919list of source directories, including theur subdirectories. 3920 3921@end itemize 3922 3923@item @b{Source Files} 3924 3925@itemize @bullet 3926 3927@item @b{Source_Files}: list 3928 3929Value is a list of source file simple names. 3930 3931@item @b{Locally_Removed_Files}: list 3932 3933Obsolescent. Equivalent to Excluded_Source_Files. 3934 3935@item @b{Excluded_Source_Files}: list 3936 3937Value is a list of simple file names that are not sources of the project. 3938Allows to remove sources that are inherited or found in the source directories 3939and that match the naming scheme. 3940 3941@item @b{Source_List_File}: single 3942 3943Value is a text file name that contains a list of source file simple names, 3944one on each line. 3945 3946@item @b{Excluded_Source_List_File}: single 3947 3948Value is a text file name that contains a list of file simple names that 3949are not sources of the project. 3950 3951@item @b{Interfaces}: list 3952 3953Value is a list of file names that constitutes the interfaces of the project. 3954 3955@end itemize 3956 3957@item @b{Aggregate Projects} 3958 3959@itemize @bullet 3960 3961@item @b{Project_Files}: list 3962 3963Value is the list of aggregated projects. 3964 3965@item @b{Project_Path}: list 3966 3967Value is a list of directories that are added to the project search path when 3968looking for the aggregated projects. 3969 3970@item @b{External}: single, indexed 3971 3972Index is the name of an external reference. Value is the value of the 3973external reference to be used when parsing the aggregated projects. 3974 3975@end itemize 3976 3977@item @b{Libraries} 3978 3979@itemize @bullet 3980 3981@item @b{Library_Dir}: single 3982 3983Value is the name of the library directory. This attribute needs to be 3984declared for each library project. 3985 3986@item @b{Library_Name}: single 3987 3988Value is the name of the library. This attribute needs to be declared or 3989inherited for each library project. 3990 3991@item @b{Library_Kind}: single 3992 3993Specifies the kind of library: static library (archive) or shared library. 3994Case-insensitive values must be one of "static" for archives (the default) or 3995"dynamic" or "relocatable" for shared libraries. 3996 3997@item @b{Library_Version}: single 3998 3999Value is the name of the library file. 4000 4001@item @b{Library_Interface}: list 4002 4003Value is the list of unit names that constitutes the interfaces 4004of a Stand-Alone Library project. 4005 4006@item @b{Library_Standalone}: single 4007 4008Specifies if a Stand-Alone Library (SAL) is encapsulated or not. 4009Only authorized case-insensitive values are "standard" for non encapsulated 4010SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project. 4011 4012@item @b{Library_Encapsulated_Options}: list 4013 4014Value is a list of options that need to be used when linking an encapsulated 4015Stand-Alone Library. 4016 4017@item @b{Library_Encapsulated_Supported}: single 4018 4019Indicates if encapsulated Stand-Alone Libraries are supported. Only 4020authorized case-insensitive values are "true" and "false" (the default). 4021 4022@item @b{Library_Auto_Init}: single 4023 4024Indicates if a Stand-Alone Library is auto-initialized. Only authorized 4025case-insentive values are "true" and "false". 4026 4027@item @b{Leading_Library_Options}: list 4028 4029Value is a list of options that are to be used at the beginning of 4030the command line when linking a shared library. 4031 4032@item @b{Library_Options}: list 4033 4034Value is a list of options that are to be used when linking a shared library. 4035 4036@item @b{Library_Rpath_Options}: list, indexed, case-insensitive index 4037 4038Index is a language name. Value is a list of options for an invocation of the 4039compiler of the language. This invocation is done for a shared library project 4040with sources of the language. The output of the invocation is the path name 4041of a shared library file. The directory name is to be put in the run path 4042option switch when linking the shared library for the project. 4043 4044@item @b{Library_Src_Dir}: single 4045 4046Value is the name of the directory where copies of the sources of the 4047interfaces of a Stand-Alone Library are to be copied. 4048 4049@item @b{Library_ALI_Dir}: single 4050 4051Value is the name of the directory where the ALI files of the interfaces 4052of a Stand-Alone Library are to be copied. When this attribute is not declared, 4053the directory is the library directory. 4054 4055@item @b{Library_gcc}: single 4056 4057Obsolescent attribute. Specify the linker driver used to link a shared library. 4058Use instead attribute Linker'Driver. 4059 4060@item @b{Library_Symbol_File}: single 4061 4062Value is the name of the library symbol file. 4063 4064@item @b{Library_Symbol_Policy}: single 4065 4066Indicates the symbol policy kind. Only authorized case-insensitive values are 4067"autonomous", "default", "compliant", "controlled" or "direct". 4068 4069@item @b{Library_Reference_Symbol_File}: single 4070 4071Value is the name of the reference symbol file. 4072 4073@end itemize 4074 4075@item @b{Configuration - General} 4076 4077@itemize @bullet 4078 4079@item @b{Default_Language}: single 4080 4081Value is the case-insensitive name of the language of a project when attribute 4082Languages is not specified. 4083 4084@item @b{Run_Path_Option}: list 4085 4086Value is the list of switches to be used when specifying the run path option 4087in an executable. 4088 4089@item @b{Run_Path_Origin}: single 4090 4091Value is the the string that may replace the path name of the executable 4092directory in the run path options. 4093 4094@item @b{Separate_Run_Path_Options}: single 4095 4096Indicates if there may be several run path options specified when linking an 4097executable. Only authorized case-insensitive values are "true" or "false" (the 4098default). 4099 4100@item @b{Toolchain_Version}: single, indexed, case-insensitive index 4101 4102Index is a language name. Specify the version of a toolchain for a language. 4103 4104@item @b{Toolchain_Description}: single, indexed, case-insensitive index 4105 4106Obsolescent. No longer used. 4107 4108@item @b{Object_Generated}: single, indexed, case-insensitive index 4109 4110Index is a language name. Indicates if invoking the compiler for a language 4111produces an object file. Only authorized case-insensitive values are "false" 4112and "true" (the default). 4113 4114@item @b{Objects_Linked}: single, indexed, case-insensitive index 4115 4116Index is a language name. Indicates if the object files created by the compiler 4117for a language need to be linked in the executable. Only authorized 4118case-insensitive values are "false" and "true" (the default). 4119 4120@item @b{Target}: single 4121 4122Value is the name of the target platform. Taken into account only in the main 4123project. 4124 4125@item @b{Runtime}: single, indexed, case-insensitive index 4126 4127Index is a language name. Indicates the runtime directory that is to be used 4128when using the compiler of the language. Taken into account only in the main 4129project. 4130 4131@end itemize 4132 4133@item @b{Configuration - Libraries} 4134 4135@itemize @bullet 4136 4137@item @b{Library_Builder}: single 4138 4139Value is the path name of the application that is to be used to build 4140libraries. Usually the path name of "gprlib". 4141 4142@item @b{Library_Support}: single 4143 4144Indicates the level of support of libraries. Only authorized case-insensitive 4145values are "static_only", "full" or "none" (the default). 4146 4147@end itemize 4148 4149@item @b{Configuration - Archives} 4150 4151@itemize @bullet 4152 4153@item @b{Archive_Builder}: list 4154 4155Value is the name of the application to be used to create a static library 4156(archive), followed by the options to be used. 4157 4158@item @b{Archive_Builder_Append_Option}: list 4159 4160Value is the list of options to be used when invoking the archive builder 4161to add project files into an archive. 4162 4163@item @b{Archive_Indexer}: list 4164 4165Value is the name of the archive indexer, followed by the required options. 4166 4167@item @b{Archive_Suffix}: single 4168 4169Value is the extension of archives. When not declared, the extension is ".a". 4170 4171@item @b{Library_Partial_Linker}: list 4172 4173Value is the name of the partial linker executable, followed by the required 4174options. 4175 4176@end itemize 4177 4178@item @b{Configuration - Shared Libraries} 4179 4180@itemize @bullet 4181 4182@item @b{Shared_Library_Prefix}: single 4183 4184Value is the prefix in the name of shared library files. When not declared, 4185the prefix is "lib". 4186 4187@item @b{Shared_Library_Suffix}: single 4188 4189Value is the the extension of the name of shared library files. When not 4190declared, the extension is ".so". 4191 4192@item @b{Symbolic_Link_Supported}: single 4193 4194Indicates if symbolic links are supported on the platform. Only authorized 4195case-insensitive values are "true" and "false" (the default). 4196 4197@item @b{Library_Major_Minor_Id_Supported}: single 4198 4199Indicates if major and minor ids for shared library names are supported on 4200the platform. Only authorized case-insensitive values are "true" and "false" 4201(the default). 4202 4203@item @b{Library_Auto_Init_Supported}: single 4204 4205Indicates if auto-initialization of Stand-Alone Libraries is supported. Only 4206authorized case-insensitive values are "true" and "false" (the default). 4207 4208@item @b{Shared_Library_Minimum_Switches}: list 4209 4210Value is the list of required switches when linking a shared library. 4211 4212@item @b{Library_Version_Switches}: list 4213 4214Value is the list of switches to specify a internal name for a shared library. 4215 4216@item @b{Library_Install_Name_Option}: single 4217 4218Value is the name of the option that needs to be used, concatenated with the 4219path name of the library file, when linking a shared library. 4220 4221@item @b{Runtime_Library_Dir}: single, indexed, case-insensitive index 4222 4223Index is a language name. Value is the path name of the directory where the 4224runtime libraries are located. 4225 4226@item @b{Runtime_Source_Dir}: single, indexed, case-insensitive index 4227 4228Index is a language name. Value is the path name of the directory where the 4229sources of runtime libraries are located. 4230 4231@end itemize 4232 4233@end itemize 4234 4235@node Package Binder Attributes 4236@subsubsection Package Binder Attributes 4237 4238@itemize @bullet 4239 4240@item @b{General} 4241 4242@itemize @bullet 4243 4244@item @b{Default_Switches}: list, indexed, case-insensitive index 4245 4246Index is a language name. Value is the list of switches to be used when binding 4247code of the language, if there is no applicable attribute Switches. 4248 4249@item @b{Switches}: list, optional index, indexed, 4250 case-insensitive index, others allowed 4251 4252Index is either a language name or a source file name. Value is the list of 4253switches to be used when binding code. Index is either the source file name 4254of the executable to be bound or the language name of the code to be bound. 4255 4256@end itemize 4257 4258@item @b{Configuration - Binding} 4259 4260@itemize @bullet 4261 4262@item @b{Driver}: single, indexed, case-insensitive index 4263 4264Index is a language name. Value is the name of the application to be used when 4265binding code of the language. 4266 4267@item @b{Required_Switches}: list, indexed, case-insensitive index 4268 4269Index is a language name. Value is the list of the required switches to be 4270used when binding code of the language. 4271 4272@item @b{Prefix}: single, indexed, case-insensitive index 4273 4274Index is a language name. Value is a prefix to be used for the binder exchange 4275file name for the language. Used to have different binder exchange file names 4276when binding different languages. 4277 4278@item @b{Objects_Path}: single,indexed, case-insensitive index 4279 4280Index is a language name. Value is the name of the environment variable that 4281contains the path for the object directories. 4282 4283@item @b{Object_Path_File}: single,indexed, case-insensitive index 4284 4285Index is a language name. Value is the name of the environment variable. The 4286value of the environment variable is the path name of a text file that 4287contains the list of object directories. 4288 4289@end itemize 4290 4291@end itemize 4292 4293@node Package Builder Attributes 4294@subsubsection Package Builder Attributes 4295 4296@itemize @bullet 4297 4298@item @b{Default_Switches}: list, indexed, case-insensitive index 4299 4300Index is a language name. Value is the list of builder switches to be used when 4301building an executable of the language, if there is no applicable attribute 4302Switches. 4303 4304@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4305 others allowed 4306 4307Index is either a language name or a source file name. Value is the list of 4308builder switches to be used when building an executable. Index is either the 4309source file name of the executable to be built or its language name. 4310 4311@item @b{Global_Compilation_Switches}: list, optional index, indexed, 4312 case-insensitive index 4313 4314Index is either a language name or a source file name. Value is the list of 4315compilation switches to be used when building an executable. Index is either 4316the source file name of the executable to be built or its language name. 4317 4318@item @b{Executable}: single, indexed, case-insensitive index 4319 4320Index is an executable source file name. Value is the simple file name of the 4321executable to be built. 4322 4323@item @b{Executable_Suffix}: single 4324 4325Value is the extension of the file names of executable. When not specified, 4326the extension is the default extension of executables on the platform. 4327 4328@item @b{Global_Configuration_Pragmas}: single 4329 4330Value is the file name of a configuration pragmas file that is specified to 4331the Ada compiler when compiling any Ada source in the project tree. 4332 4333@item @b{Global_Config_File}: single, indexed, case-insensitive index 4334 4335Index is a language name. Value is the file name of a configuration file that 4336is specified to the compiler when compiling any source of the language in the 4337project tree. 4338 4339@end itemize 4340 4341@ifclear FSFEDITION 4342@node Package Check Attributes 4343@subsubsection Package Check Attributes 4344 4345@itemize @bullet 4346 4347@item @b{Default_Switches}: list, indexed, case-insensitive index 4348 4349Index is a language name. Value is a list of switches to be used when invoking 4350@code{gnatcheck} for a source of the language, if there is no applicable 4351attribute Switches. 4352 4353@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4354 others allowed 4355 4356Index is a source file name. Value is the list of switches to be used when 4357invoking @code{gnatcheck} for the source. 4358 4359@end itemize 4360@end ifclear 4361 4362@node Package Clean Attributes 4363@subsubsection Package Clean Attributes 4364 4365@itemize @bullet 4366 4367@item @b{Switches}: list 4368 4369Value is a list of switches to be used by the cleaning application. 4370 4371@item @b{Source_Artifact_Extensions}: list, indexed, case-insensitive index 4372 4373Index is a language names. Value is the list of extensions for file names 4374derived from object file names that need to be cleaned in the object 4375directory of the project. 4376 4377@item @b{Object_Artifact_Extensions}: list, indexed, case-insensitive index 4378 4379Index is a language names. Value is the list of extensions for file names 4380derived from source file names that need to be cleaned in the object 4381directory of the project. 4382 4383@item @b{Artifacts_In_Object_Dir}: single 4384 4385Value is a list of file names expressed as regular expressions that are to be 4386deleted by gprclean in the object directory of the project. 4387 4388@item @b{Artifacts_In_Exec_Dir}: single 4389 4390Value is list of file names expressed as regular expressions that are to be 4391deleted by gprclean in the exec directory of the main project. 4392 4393@end itemize 4394 4395@node Package Compiler Attributes 4396@subsubsection Package Compiler Attributes 4397 4398@itemize @bullet 4399 4400@item @b{General} 4401 4402@itemize @bullet 4403 4404@item @b{Default_Switches}: list, indexed, case-insensitive index 4405 4406Index is a language name. Value is a list of switches to be used when invoking 4407the compiler for the language for a source of the project, if there is no 4408applicable attribute Switches. 4409 4410@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4411 others allowed 4412 4413Index is a source file name or a language name. Value is the list of switches 4414to be used when invoking the compiler for the source or for its language. 4415 4416@item @b{Local_Configuration_Pragmas}: single 4417 4418Value is the file name of a configuration pragmas file that is specified to 4419the Ada compiler when compiling any Ada source in the project. 4420 4421@item @b{Local_Config_File}: single, indexed, case-insensitive index 4422 4423Index is a language name. Value is the file name of a configuration file that 4424is specified to the compiler when compiling any source of the language in the 4425project. 4426 4427@end itemize 4428 4429@item @b{Configuration - Compiling} 4430 4431@itemize @bullet 4432 4433@item @b{Driver}: single, indexed, case-insensitive index 4434 4435Index is a language name. Value is the name of the executable for the compiler 4436of the language. 4437 4438@item @b{Language_Kind}: single, indexed, case-insensitive index 4439 4440Index is a language name. Indicates the kind of the language, either file based 4441or unit based. Only authorized case-insensitive values are "unit_based" and 4442"file_based" (the default). 4443 4444@item @b{Dependency_Kind}: single, indexed, case-insensitive index 4445 4446Index is a language name. Indicates how the dependencies are handled for the 4447language. Only authorized case-insensitive values are "makefile", "ali_file", 4448"ali_closure" or "none" (the default). 4449 4450@item @b{Required_Switches}: list, indexed, case-insensitive index 4451 4452Equivalent to attribute Leading_Required_Switches. 4453 4454@item @b{Leading_Required_Switches}: list, indexed, case-insensitive index 4455 4456Index is a language name. Value is the list of the minimum switches to be used 4457at the beginning of the command line when invoking the compiler for the 4458language. 4459 4460@item @b{Trailing_Required_Switches}: list, indexed, case-insensitive index 4461 4462Index is a language name. Value is the list of the minimum switches to be used 4463at the end of the command line when invoking the compiler for the language. 4464 4465@item @b{PIC_Option}: list, indexed, case-insensitive index 4466 4467Index is a language name. Value is the list of switches to be used when 4468compiling a source of the language when the project is a shared library 4469project. 4470 4471@item @b{Path_Syntax}: single, indexed, case-insensitive index 4472 4473Index is a language name. Value is the kind of path syntax to be used when 4474invoking the compiler for the language. Only authorized case-insensitive 4475values are "canonical" and "host" (the default). 4476 4477@item @b{Source_File_Switches}: single, indexed, case-insensitive index 4478 4479Index is a language name. Value is a list of switches to be used just before 4480the path name of the source to compile when invoking the compiler for a source 4481of the language. 4482 4483@item @b{Object_File_Suffix}: single, indexed, case-insensitive index 4484 4485Index is a language name. Value is the extension of the object files created 4486by the compiler of the language. When not specified, the extension is the 4487default one for the platform. 4488 4489@item @b{Object_File_Switches}: list, indexed, case-insensitive index 4490 4491Index is a language name. Value is the list of switches to be used by the 4492compiler of the language to specify the path name of the object file. When not 4493specified, the switch used is "-o". 4494 4495@item @b{Multi_Unit_Switches}: list, indexed, case-insensitive index 4496 4497Index is a language name. Value is the list of switches to be used to compile 4498a unit in a multi unit source of the language. The index of the unit in the 4499source is concatenated with the last switches in the list. 4500 4501@item @b{Multi_Unit_Object_Separator}: single, indexed, case-insensitive index 4502 4503Index is a language name. Value is the string to be used in the object file 4504name before the index of the unit, when compiling a unit in a multi unit source 4505of the language. 4506 4507@end itemize 4508 4509@item @b{Configuration - Mapping Files} 4510 4511@itemize @bullet 4512 4513@item @b{Mapping_File_Switches}: list, indexed, case-insensitive index 4514 4515Index is a language name. Value is the list of switches to be used to specify 4516a mapping file when invoking the compiler for a source of the language. 4517 4518@item @b{Mapping_Spec_Suffix}: single, indexed, case-insensitive index 4519 4520Index is a language name. Value is the suffix to be used in a mapping file 4521to indicate that the source is a spec. 4522 4523@item @b{Mapping_Body_Suffix}: single, indexed, case-insensitive index 4524 4525Index is a language name. Value is the suffix to be used in a mapping file 4526to indicate that the source is a body. 4527 4528@end itemize 4529 4530@item @b{Configuration - Config Files} 4531 4532@itemize @bullet 4533 4534@item @b{Config_File_Switches}: list: single, indexed, case-insensitive index 4535 4536Index is a language name. Value is the list of switches to specify to the 4537compiler of the language a configuration file. 4538 4539@item @b{Config_Body_File_Name}: single, indexed, case-insensitive index 4540 4541Index is a language name. Value is the template to be used to indicate a 4542configuration specific to a body of the language in a configuration 4543file. 4544 4545@item @b{Config_Body_File_Name_Index}: single, indexed, case-insensitive index 4546 4547Index is a language name. Value is the template to be used to indicate a 4548configuration specific to the body a unit in a multi unit source of the 4549language in a configuration file. 4550 4551@item @b{Config_Body_File_Name_Pattern}: single, indexed, 4552 case-insensitive index 4553 4554Index is a language name. Value is the template to be used to indicate a 4555configuration for all bodies of the languages in a configuration file. 4556 4557@item @b{Config_Spec_File_Name}: single, indexed, case-insensitive index 4558 4559Index is a language name. Value is the template to be used to indicate a 4560configuration specific to a spec of the language in a configuration 4561file. 4562 4563@item @b{Config_Spec_File_Name_Index}: single, indexed, case-insensitive index 4564 4565Index is a language name. Value is the template to be used to indicate a 4566configuration specific to the spec a unit in a multi unit source of the 4567language in a configuration file. 4568 4569@item @b{Config_Spec_File_Name_Pattern}: single, indexed, 4570 case-insensitive index 4571 4572Index is a language name. Value is the template to be used to indicate a 4573configuration for all specs of the languages in a configuration file. 4574 4575@item @b{Config_File_Unique}: single, indexed, case-insensitive index 4576 4577Index is a language name. Indicates if there should be only one configuration 4578file specified to the compiler of the language. Only authorized 4579case-insensitive values are "true" and "false" (the default). 4580 4581@end itemize 4582 4583@item @b{Configuration - Dependencies} 4584 4585@itemize @bullet 4586 4587@item @b{Dependency_Switches}: list, indexed, case-insensitive index 4588 4589Index is a language name. Value is the list of switches to be used to specify 4590to the compiler the dependency file when the dependency kind of the language is 4591file based, and when Dependency_Driver is not specified for the language. 4592 4593@item @b{Dependency_Driver}: list, indexed, case-insensitive index 4594 4595Index is a language name. Value is the name of the executable to be used to 4596create the dependency file for a source of the language, followed by the 4597required switches. 4598 4599@end itemize 4600 4601@item @b{Configuration - Search Paths} 4602 4603@itemize @bullet 4604 4605@item @b{Include_Switches}: list, indexed, case-insensitive index 4606 4607Index is a language name. Value is the list of switches to specify to the 4608compiler of the language to indicate a directory to look for sources. 4609 4610@item @b{Include_Path}: single, indexed, case-insensitive index 4611 4612Index is a language name. Value is the name of an environment variable that 4613contains the path of all the directories that the compiler of the language 4614may search for sources. 4615 4616@item @b{Include_Path_File}: single, indexed, case-insensitive index 4617 4618Index is a language name. Value is the name of an environment variable the 4619value of which is the path name of a text file that contains the directories 4620that the compiler of the language may search for sources. 4621 4622@item @b{Object_Path_Switches}: list, indexed, case-insensitive index 4623 4624Index is a language name. Value is the list of switches to specify to the 4625compiler of the language the name of a text file that contains the list of 4626object directories. When this attribute is not declared, the text file is 4627not created. 4628 4629@end itemize 4630 4631@end itemize 4632 4633@node Package Cross_Reference Attributes 4634@subsubsection Package Cross_Reference Attributes 4635 4636@itemize @bullet 4637 4638@item @b{Default_Switches}: list, indexed, case-insensitive index 4639 4640Index is a language name. Value is a list of switches to be used when invoking 4641@code{gnatxref} for a source of the language, if there is no applicable 4642attribute Switches. 4643 4644@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4645 others allowed 4646 4647Index is a source file name. Value is the list of switches to be used when 4648invoking @code{gnatxref} for the source. 4649 4650@end itemize 4651 4652@ifclear FSFEDITION 4653@node Package Eliminate Attributes 4654@subsubsection Package Eliminate Attributes 4655 4656@itemize @bullet 4657 4658@item @b{Default_Switches}: list, indexed, case-insensitive index 4659 4660Index is a language name. Value is a list of switches to be used when invoking 4661@code{gnatelim} for a source of the language, if there is no applicable 4662attribute Switches. 4663 4664@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4665 others allowed 4666 4667Index is a source file name. Value is the list of switches to be used when 4668invoking @code{gnatelim} for the source. 4669 4670@end itemize 4671@end ifclear 4672 4673@node Package Finder Attributes 4674@subsubsection Package Finder Attributes 4675 4676@itemize @bullet 4677 4678@item @b{Default_Switches}: list, indexed, case-insensitive index 4679 4680Index is a language name. Value is a list of switches to be used when invoking 4681@code{gnatfind} for a source of the language, if there is no applicable 4682attribute Switches. 4683 4684@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4685 others allowed 4686 4687Index is a source file name. Value is the list of switches to be used when 4688invoking @code{gnatfind} for the source. 4689 4690@end itemize 4691 4692@node Package gnatls Attributes 4693@subsubsection Package gnatls Attributes 4694 4695@itemize @bullet 4696 4697@item @b{Switches}: list 4698 4699Value is a list of switches to be used when invoking @code{gnatls}. 4700 4701@end itemize 4702 4703@ifclear FSFEDITION 4704@node Package gnatstub Attributes 4705@subsubsection Package gnatstub Attributes 4706 4707@itemize @bullet 4708 4709@item @b{Default_Switches}: list, indexed, case-insensitive index 4710 4711Index is a language name. Value is a list of switches to be used when invoking 4712@code{gnatstub} for a source of the language, if there is no applicable 4713attribute Switches. 4714 4715@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4716 others allowed 4717 4718Index is a source file name. Value is the list of switches to be used when 4719invoking @code{gnatstub} for the source. 4720 4721@end itemize 4722@end ifclear 4723 4724@node Package IDE Attributes 4725@subsubsection Package IDE Attributes 4726 4727@itemize @bullet 4728 4729@item @b{Default_Switches}: list, indexed 4730 4731Index is the name of an external tool that the GNAT Programming System (GPS) 4732is supporting. Value is a list of switches to use when invoking that tool. 4733 4734@item @b{Remote_Host}: single 4735 4736Value is a string that designates the remote host in a cross-compilation 4737environment, to be used for remote compilation and debugging. This attribute 4738should not be specified when running on the local machine. 4739 4740@item @b{Program_Host}: single 4741 4742Value is a string that specifies the name of IP address of the embedded target 4743in a cross-compilation environment, on which the program should execute. 4744 4745@item @b{Communication_Protocol}: single 4746 4747Value is the name of the protocol to use to communicate with the target 4748in a cross-compilation environment, for example @code{"wtx"} or 4749@code{"vxworks"}. 4750 4751@item @b{Compiler_Command}: single, indexed, case-insensitive index 4752 4753Index is a language Name. Value is a string that denotes the command to be 4754used to invoke the compiler. The value of @code{Compiler_Command ("Ada")} is 4755expected to be compatible with @command{gnatmake}, in particular in 4756the handling of switches. 4757 4758@item @b{Debugger_Command}: single 4759 4760Value is a string that specifies the name of the debugger to be used, such as 4761gdb, powerpc-wrs-vxworks-gdb or gdb-4. 4762 4763@item @b{gnatlist}: single 4764 4765Value is a string that specifies the name of the @command{gnatls} utility 4766to be used to retrieve information about the predefined path; for example, 4767@code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. 4768 4769@item @b{VCS_Kind}: single 4770 4771Value is a string used to specify the Version Control System (VCS) to be used 4772for this project, for example "Subversion", "ClearCase". If the 4773value is set to "Auto", the IDE will try to detect the actual VCS used 4774on the list of supported ones. 4775 4776@item @b{VCS_File_Check}: single 4777 4778Value is a string that specifies the command used by the VCS to check 4779the validity of a file, either when the user explicitly asks for a check, 4780or as a sanity check before doing the check-in. 4781 4782@item @b{VCS_Log_Check}: single 4783 4784Value is a string that specifies the command used by the VCS to check 4785the validity of a log file. 4786 4787@item @b{Documentation_Dir}: single 4788 4789Value is the directory used to generate the documentation of source code. 4790 4791@end itemize 4792 4793@node Package Install Attributes 4794@subsubsection Package Install Attributes 4795 4796@itemize @bullet 4797 4798@item @b{Artifacts}: list, indexed 4799 4800An array attribute to declare a set of files not part of the sources 4801to be installed. The array discriminant is the directory where the 4802file is to be installed. If a relative directory then Prefix (see 4803below) is prepended. 4804 4805@item @b{Prefix}: single 4806 4807Value is the install destination directory. 4808 4809@item @b{Sources_Subdir}: single 4810 4811Value is the sources directory or subdirectory of Prefix. 4812 4813@item @b{Exec_Subdir}: single 4814 4815Value is the executables directory or subdirectory of Prefix. 4816 4817@item @b{Lib_Subdir}: single 4818 4819Value is library directory or subdirectory of Prefix. 4820 4821@item @b{Project_Subdir}: single 4822 4823Value is the project directory or subdirectory of Prefix. 4824 4825@item @b{Active}: single 4826 4827Indicates that the project is to be installed or not. Case-insensitive value 4828"false" means that the project is not to be installed, all other values mean 4829that the project is to be installed. 4830 4831@item @b{Mode}: single 4832 4833Value is the installation mode, it is either @b{dev} (default) or @b{usage}. 4834 4835@item @b{Install_Name}: single 4836 4837Specify the name to use for recording the installation. The default is 4838the project name without the extension. 4839 4840@end itemize 4841 4842@node Package Linker Attributes 4843@subsubsection Package Linker Attributes 4844 4845@itemize @bullet 4846 4847@item @b{General} 4848 4849@itemize @bullet 4850 4851@item @b{Required_Switches}: list 4852 4853Value is a list of switches that are required when invoking the linker to link 4854an executable. 4855 4856@item @b{Default_Switches}: list, indexed, case-insensitive index 4857 4858Index is a language name. Value is a list of switches for the linker when 4859linking an executable for a main source of the language, when there is no 4860applicable Switches. 4861 4862@item @b{Leading_Switches}: list, optional index, indexed, 4863 case-insensitive index, others allowed 4864 4865Index is a source file name or a language name. Value is the list of switches 4866to be used at the beginning of the command line when invoking the linker to 4867build an executable for the source or for its language. 4868 4869@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4870 others allowed 4871 4872Index is a source file name or a language name. Value is the list of switches 4873to be used when invoking the linker to build an executable for the source or 4874for its language. 4875 4876@item @b{Trailing_Switches}: list, optional index, indexed, 4877 case-insensitive index, others allowed 4878 4879Index is a source file name or a language name. Value is the list of switches 4880to be used at the end of the command line when invoking the linker to 4881build an executable for the source or for its language. These switches may 4882override the Required_Switches. 4883 4884@item @b{Linker_Options}: list 4885 4886Value is a list of switches/options that are to be added when linking an 4887executable from a project importing the current project directly or indirectly. 4888Linker_Options are not used when linking an executable from the current 4889project. 4890 4891@item @b{Map_File_Option}: single 4892 4893Value is the switch to specify the map file name that the linker needs to 4894create. 4895 4896@end itemize 4897 4898@item @b{Configuration - Linking} 4899 4900@itemize @bullet 4901 4902@item @b{Driver}: single 4903 4904Value is the name of the linker executable. 4905 4906@end itemize 4907 4908@item @b{Configuration - Response Files} 4909 4910@itemize @bullet 4911 4912@item @b{Max_Command_Line_Length}: single 4913 4914Value is the maximum number of character in the command line when invoking 4915the linker to link an executable. 4916 4917@item @b{Response_File_Format}: single 4918 4919Indicates the kind of response file to create when the length of the linking 4920command line is too large. Only authorized case-insensitive values are "none", 4921"gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list". 4922 4923@item @b{Response_File_Switches}: list 4924 4925Value is the list of switches to specify a response file to the linker. 4926 4927@end itemize 4928 4929@end itemize 4930 4931@ifclear FSFEDITION 4932@node Package Metrics Attribute 4933@subsubsection Package Metrics Attribute 4934 4935@itemize @bullet 4936 4937@item @b{Default_Switches}: list, indexed, case-insensitive index 4938 4939Index is a language name. Value is a list of switches to be used when invoking 4940@code{gnatmetric} for a source of the language, if there is no applicable 4941attribute Switches. 4942 4943@item @b{Switches}: list, optional index, indexed, case-insensitive index, 4944 others allowed 4945 4946Index is a source file name. Value is the list of switches to be used when 4947invoking @code{gnatmetric} for the source. 4948 4949@end itemize 4950@end ifclear 4951 4952@node Package Naming Attributes 4953@subsubsection Package Naming Attributes 4954 4955@itemize @bullet 4956 4957@item @b{Specification_Suffix}: single, indexed, case-insensitive index 4958 4959Equivalent to attribute Spec_Suffix. 4960 4961@item @b{Spec_Suffix}: single, indexed, case-insensitive index 4962 4963Index is a language name. Value is the extension of file names for specs of 4964the language. 4965 4966@item @b{Implementation_Suffix}: single, indexed, case-insensitive index 4967 4968Equivalent to attribute Body_Suffix. 4969 4970@item @b{Body_Suffix}: single, indexed, case-insensitive index 4971 4972Index is a language name. Value is the extension of file names for bodies of 4973the language. 4974 4975@item @b{Separate_Suffix}: single 4976 4977Value is the extension of file names for subunits of Ada. 4978 4979@item @b{Casing}: single 4980 4981Indicates the casing of sources of the Ada language. Only authorized 4982case-insensitive values are "lowercase", "uppercase" and "mixedcase". 4983 4984@item @b{Dot_Replacement}: single 4985 4986Value is the string that replace the dot of unit names in the source file names 4987of the Ada language. 4988 4989@item @b{Specification}: single, optional index, indexed, 4990 case-insensitive index 4991 4992Equivalent to attribute Spec. 4993 4994@item @b{Spec}: single, optional index, indexed, case-insensitive index 4995 4996Index is a unit name. Value is the file name of the spec of the unit. 4997 4998@item @b{Implementation}: single, optional index, indexed, 4999 case-insensitive index 5000 5001Equivalent to attribute Body. 5002 5003@item @b{Body}: single, optional index, indexed, case-insensitive index 5004 5005Index is a unit name. Value is the file name of the body of the unit. 5006 5007@item @b{Specification_Exceptions}: list, indexed, case-insensitive index 5008 5009Index is a language name. Value is a list of specs for the language that do not 5010necessarily follow the naming scheme for the language and that may or may not 5011be found in the source directories of the project. 5012 5013@item @b{Implementation_Exceptions}: list, indexed, case-insensitive index 5014 5015Index is a language name. Value is a list of bodies for the language that do not 5016necessarily follow the naming scheme for the language and that may or may not 5017be found in the source directories of the project. 5018 5019@end itemize 5020 5021@ifclear FSFEDITION 5022@node Package Pretty_Printer Attributes 5023@subsubsection Package Pretty_Printer Attributes 5024 5025@itemize @bullet 5026 5027@item @b{Default_Switches}: list, indexed, case-insensitive index 5028 5029Index is a language name. Value is a list of switches to be used when invoking 5030@code{gnatpp} for a source of the language, if there is no applicable 5031attribute Switches. 5032 5033@item @b{Switches}: list, optional index, indexed, case-insensitive index, 5034 others allowed 5035 5036Index is a source file name. Value is the list of switches to be used when 5037invoking @code{gnatpp} for the source. 5038 5039@end itemize 5040@end ifclear 5041 5042@node Package Remote Attributes 5043@subsubsection Package Remote Attributes 5044 5045@itemize @bullet 5046 5047@item @b{Included_Patterns}: list 5048 5049If this attribute is defined it sets the patterns to 5050synchronized from the master to the slaves. It is exclusive 5051with Excluded_Patterns, that is it is an error to define 5052both. 5053 5054@item @b{Included_Artifact_Patterns}: list 5055 5056If this attribute is defined it sets the patterns of compilation 5057artifacts to synchronized from the slaves to the build master. 5058This attribute replace the default hard-coded patterns. 5059 5060@item @b{Excluded_Patterns}: list 5061 5062Set of patterns to ignore when synchronizing sources from the build 5063master to the slaves. A set of predefined patterns are supported 5064(e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to 5065add some more patterns. 5066 5067@item @b{Root_Dir}: single 5068 5069Value is the root directory used by the slave machines. 5070 5071@end itemize 5072 5073@node Package Stack Attributes 5074@subsubsection Package Stack Attributes 5075 5076@itemize @bullet 5077 5078@item @b{Switches}: list 5079 5080Value is the list of switches to be used when invoking @code{gnatstack}. 5081 5082@end itemize 5083 5084@node Package Synchronize Attributes 5085@subsubsection Package Synchronize Attributes 5086 5087@itemize @bullet 5088 5089@item @b{Default_Switches}: list, indexed, case-insensitive index 5090 5091Index is a language name. Value is a list of switches to be used when invoking 5092@code{gnatsync} for a source of the language, if there is no applicable 5093attribute Switches. 5094 5095@item @b{Switches}: list, optional index, indexed, case-insensitive index, 5096 others allowed 5097 5098Index is a source file name. Value is the list of switches to be used when 5099invoking @code{gnatsync} for the source. 5100 5101@end itemize 5102