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