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