gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst

   1 .. _Tools_Supporting_Project_Files:
   2
   3 Tools Supporting Project Files
   4 ==============================
   5
   6 This section describes how project files can be used in conjunction with a number of
   7 GNAT tools.
   8
   9 .. _gnatmake_and_Project_Files:
  10
  11 gnatmake and Project Files
  12 --------------------------
  13
  14 This section covers several topics related to *gnatmake* and
  15 project files: defining switches for *gnatmake*
  16 and for the tools that it invokes; specifying configuration pragmas;
  17 the use of the `Main` attribute; building and rebuilding library project
  18 files.
  19
  20 .. _Switches_Related_to_Project_Files:
  21
  22 Switches Related to Project Files
  23 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  24
  25 The following switches are used by GNAT tools that support project files:
  26
  27
  28   .. index:: -P (any project-aware tool)
  29
  30 :samp:`-P{project}`
  31   Indicates the name of a project file. This project file will be parsed with
  32   the verbosity indicated by *-vP*x**,
  33   if any, and using the external references indicated
  34   by *-X* switches, if any.
  35   There may zero, one or more spaces between *-P* and `project`.
  36
  37   There must be only one *-P* switch on the command line.
  38
  39   Since the Project Manager parses the project file only after all the switches
  40   on the command line are checked, the order of the switches
  41   *-P*,
  42   *-vP*x**
  43   or *-X* is not significant.
  44
  45
  46   .. index:: -X (any project-aware tool)
  47
  48 :samp:`-X{name}={value}`
  49   Indicates that external variable `name` has the value `value`.
  50   The Project Manager will use this value for occurrences of
  51   `external(name)` when parsing the project file.
  52
  53   If `name` or `value` includes a space, then `name=value` should be
  54   put between quotes.
  55
  56   ::
  57
  58       -XOS=NT
  59       -X"user=John Doe"
  60
  61   Several *-X* switches can be used simultaneously.
  62   If several *-X* switches specify the same
  63   `name`, only the last one is used.
  64
  65   An external variable specified with a *-X* switch
  66   takes precedence over the value of the same name in the environment.
  67
  68
  69   .. index:: -vP (any project-aware tool)
  70
  71 :samp:`-vP{x}`
  72   Indicates the verbosity of the parsing of GNAT project files.
  73
  74   *-vP0* means Default;
  75   *-vP1* means Medium;
  76   *-vP2* means High.
  77
  78   The default is Default: no output for syntactically correct
  79   project files.
  80   If several *-vP*x** switches are present,
  81   only the last one is used.
  82
  83
  84   .. index:: -aP (any project-aware tool)
  85
  86 :samp:`-aP{dir}`
  87   Add directory `dir` at the beginning of the project search path, in order,
  88   after the current working directory.
  89
  90
  91   .. index:: -eL (any project-aware tool)
  92
  93 :samp:`-eL`
  94   Follow all symbolic links when processing project files.
  95
  96
  97   .. index:: --subdirs= (gnatmake and gnatclean)
  98
  99 :samp:`--subdirs={subdir}`
 100   This switch is recognized by *gnatmake* and *gnatclean*. It
 101   indicate that the real directories (except the source directories) are the
 102   subdirectories `subdir` of the directories specified in the project files.
 103   This applies in particular to object directories, library directories and
 104   exec directories. If the subdirectories do not exist, they are created
 105   automatically.
 106
 107
 108 .. _Switches_and_Project_Files:
 109
 110 Switches and Project Files
 111 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 112
 113 For each of the packages `Builder`, `Compiler`, `Binder`, and
 114 `Linker`, you can specify a `Default_Switches`
 115 attribute, a `Switches` attribute, or both;
 116 as their names imply, these switch-related
 117 attributes affect the switches that are used for each of these GNAT
 118 components when
 119 *gnatmake* is invoked.  As will be explained below, these
 120 component-specific switches precede
 121 the switches provided on the *gnatmake* command line.
 122
 123 The `Default_Switches` attribute is an attribute
 124 indexed by language name (case insensitive) whose value is a string list.
 125 For example:
 126
 127   .. code-block:: gpr
 128
 129      package Compiler is
 130        for Default_Switches ("Ada")
 131            use ("-gnaty",
 132                 "-v");
 133      end Compiler;
 134
 135 The `Switches` attribute is indexed on a file name (which may or may
 136 not be case sensitive, depending
 137 on the operating system) whose value is a string list.  For example:
 138
 139   .. code-block:: gpr
 140
 141      package Builder is
 142         for Switches ("main1.adb")
 143             use ("-O2");
 144         for Switches ("main2.adb")
 145             use ("-g");
 146      end Builder;
 147
 148 For the `Builder` package, the file names must designate source files
 149 for main subprograms.  For the `Binder` and `Linker` packages, the
 150 file names must designate :file:`ALI` or source files for main subprograms.
 151 In each case just the file name without an explicit extension is acceptable.
 152
 153 For each tool used in a program build (*gnatmake*, the compiler, the
 154 binder, and the linker), the corresponding package @dfn{contributes} a set of
 155 switches for each file on which the tool is invoked, based on the
 156 switch-related attributes defined in the package.
 157 In particular, the switches
 158 that each of these packages contributes for a given file `f` comprise:
 159
 160 * the value of attribute `Switches (`f`)`,
 161   if it is specified in the package for the given file,
 162 * otherwise, the value of `Default_Switches ("Ada")`,
 163   if it is specified in the package.
 164
 165 If neither of these attributes is defined in the package, then the package does
 166 not contribute any switches for the given file.
 167
 168 When *gnatmake* is invoked on a file, the switches comprise
 169 two sets, in the following order: those contributed for the file
 170 by the `Builder` package;
 171 and the switches passed on the command line.
 172
 173 When *gnatmake* invokes a tool (compiler, binder, linker) on a file,
 174 the switches passed to the tool comprise three sets,
 175 in the following order:
 176
 177 * the applicable switches contributed for the file
 178   by the `Builder` package in the project file supplied on the command line;
 179
 180 * those contributed for the file by the package (in the relevant project file --
 181   see below) corresponding to the tool; and
 182
 183 * the applicable switches passed on the command line.
 184
 185 The term *applicable switches* reflects the fact that
 186 *gnatmake* switches may or may not be passed to individual
 187 tools, depending on the individual switch.
 188
 189 *gnatmake* may invoke the compiler on source files from different
 190 projects. The Project Manager will use the appropriate project file to
 191 determine the `Compiler` package for each source file being compiled.
 192 Likewise for the `Binder` and `Linker` packages.
 193
 194 As an example, consider the following package in a project file:
 195
 196
 197   .. code-block:: gpr
 198
 199      project Proj1 is
 200         package Compiler is
 201            for Default_Switches ("Ada")
 202                use ("-g");
 203            for Switches ("a.adb")
 204                use ("-O1");
 205            for Switches ("b.adb")
 206                use ("-O2",
 207                     "-gnaty");
 208         end Compiler;
 209      end Proj1;
 210
 211 If *gnatmake* is invoked with this project file, and it needs to
 212 compile, say, the files :file:`a.adb`, :file:`b.adb`, and :file:`c.adb`, then
 213 :file:`a.adb` will be compiled with the switch *-O1*,
 214 :file:`b.adb` with switches *-O2* and *-gnaty*,
 215 and :file:`c.adb` with *-g*.
 216
 217 The following example illustrates the ordering of the switches
 218 contributed by different packages:
 219
 220   .. code-block:: gpr
 221
 222      project Proj2 is
 223         package Builder is
 224            for Switches ("main.adb")
 225                use ("-g",
 226                     "-O1",
 227                     "-f");
 228         end Builder;
 229
 230         package Compiler is
 231            for Switches ("main.adb")
 232                use ("-O2");
 233         end Compiler;
 234      end Proj2;
 235
 236 If you issue the command:
 237
 238   ::
 239
 240       $ gnatmake -Pproj2 -O0 main
 241
 242 then the compiler will be invoked on :file:`main.adb` with the following
 243 sequence of switches
 244
 245   ::
 246
 247       -g -O1 -O2 -O0
 248
 249 with the last *-O*
 250 switch having precedence over the earlier ones;
 251 several other switches
 252 (such as *-c*) are added implicitly.
 253
 254 The switches *-g*
 255 and *-O1* are contributed by package
 256 `Builder`,  *-O2* is contributed
 257 by the package `Compiler`
 258 and *-O0* comes from the command line.
 259
 260 The *-g* switch will also be passed in the invocation of
 261 *Gnatlink.*
 262
 263 A final example illustrates switch contributions from packages in different
 264 project files:
 265
 266   .. code-block:: gpr
 267
 268      project Proj3 is
 269         for Source_Files use ("pack.ads", "pack.adb");
 270         package Compiler is
 271            for Default_Switches ("Ada")
 272                use ("-gnata");
 273         end Compiler;
 274      end Proj3;
 275
 276      with "Proj3";
 277      project Proj4 is
 278         for Source_Files use ("foo_main.adb", "bar_main.adb");
 279         package Builder is
 280            for Switches ("foo_main.adb")
 281                use ("-s",
 282                     "-g");
 283         end Builder;
 284      end Proj4;
 285
 286   .. code-block:: ada
 287
 288      -- Ada source file:
 289      with Pack;
 290      procedure Foo_Main is
 291         ...
 292      end Foo_Main;
 293
 294 If the command is
 295
 296   ::
 297
 298      $ gnatmake -PProj4 foo_main.adb -cargs -gnato
 299
 300 then the switches passed to the compiler for :file:`foo_main.adb` are
 301 *-g* (contributed by the package `Proj4.Builder`) and
 302 *-gnato* (passed on the command line).
 303 When the imported package `Pack` is compiled, the switches used
 304 are *-g* from `Proj4.Builder`,
 305 *-gnata* (contributed from package `Proj3.Compiler`,
 306 and *-gnato* from the command line.
 307
 308 When using *gnatmake* with project files, some switches or
 309 arguments may be expressed as relative paths. As the working directory where
 310 compilation occurs may change, these relative paths are converted to absolute
 311 paths. For the switches found in a project file, the relative paths
 312 are relative to the project file directory, for the switches on the command
 313 line, they are relative to the directory where *gnatmake* is invoked.
 314 The switches for which this occurs are:
 315 -I,
 316 -A,
 317 -L,
 318 -aO,
 319 -aL,
 320 -aI, as well as all arguments that are not switches (arguments to
 321 switch
 322 -o, object files specified in package `Linker` or after
 323 -largs on the command line). The exception to this rule is the switch
 324 --RTS= for which a relative path argument is never converted.
 325
 326 .. _Specifying_Configuration_Pragmas:
 327
 328 Specifying Configuration Pragmas
 329 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 330
 331 When using *gnatmake* with project files, if there exists a file
 332 :file:`gnat.adc` that contains configuration pragmas, this file will be
 333 ignored.
 334
 335 Configuration pragmas can be defined by means of the following attributes in
 336 project files: `Global_Configuration_Pragmas` in package `Builder`
 337 and `Local_Configuration_Pragmas` in package `Compiler`.
 338
 339 Both these attributes are single string attributes. Their values is the path
 340 name of a file containing configuration pragmas. If a path name is relative,
 341 then it is relative to the project directory of the project file where the
 342 attribute is defined.
 343
 344 When compiling a source, the configuration pragmas used are, in order,
 345 those listed in the file designated by attribute
 346 `Global_Configuration_Pragmas` in package `Builder` of the main
 347 project file, if it is specified, and those listed in the file designated by
 348 attribute `Local_Configuration_Pragmas` in package `Compiler` of
 349 the project file of the source, if it exists.
 350
 351 .. _Project_Files_and_Main_Subprograms:
 352
 353 Project Files and Main Subprograms
 354 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 355
 356 When using a project file, you can invoke *gnatmake*
 357 with one or several main subprograms, by specifying their source files on the
 358 command line.
 359
 360   ::
 361
 362       $ gnatmake -Pprj main1.adb main2.adb main3.adb
 363
 364 Each of these needs to be a source file of the same project, except
 365 when the switch `-u` is used.
 366
 367 When `-u` is not used, all the mains need to be sources of the
 368 same project, one of the project in the tree rooted at the project specified
 369 on the command line. The package `Builder` of this common project, the
 370 "main project" is the one that is considered by *gnatmake*.
 371
 372 When `-u` is used, the specified source files may be in projects
 373 imported directly or indirectly by the project specified on the command line.
 374 Note that if such a source file is not part of the project specified on the
 375 command line, the switches found in package `Builder` of the
 376 project specified on the command line, if any, that are transmitted
 377 to the compiler will still be used, not those found in the project file of
 378 the source file.
 379
 380 When using a project file, you can also invoke *gnatmake* without
 381 explicitly specifying any main, and the effect depends on whether you have
 382 defined the `Main` attribute.  This attribute has a string list value,
 383 where each element in the list is the name of a source file (the file
 384 extension is optional) that contains a unit that can be a main subprogram.
 385
 386 If the `Main` attribute is defined in a project file as a non-empty
 387 string list and the switch *-u* is not used on the command
 388 line, then invoking *gnatmake* with this project file but without any
 389 main on the command line is equivalent to invoking *gnatmake* with all
 390 the file names in the `Main` attribute on the command line.
 391
 392 Example:
 393
 394   .. code-block:: gpr
 395
 396      project Prj is
 397         for Main use ("main1.adb", "main2.adb", "main3.adb");
 398      end Prj;
 399
 400 With this project file, `"gnatmake -Pprj"`
 401 is equivalent to
 402 `"gnatmake -Pprj main1.adb main2.adb main3.adb"`.
 403
 404 When the project attribute `Main` is not specified, or is specified
 405 as an empty string list, or when the switch *-u* is used on the command
 406 line, then invoking *gnatmake* with no main on the command line will
 407 result in all immediate sources of the project file being checked, and
 408 potentially recompiled. Depending on the presence of the switch *-u*,
 409 sources from other project files on which the immediate sources of the main
 410 project file depend are also checked and potentially recompiled. In other
 411 words, the *-u* switch is applied to all of the immediate sources of the
 412 main project file.
 413
 414 When no main is specified on the command line and attribute `Main` exists
 415 and includes several mains, or when several mains are specified on the
 416 command line, the default switches in package `Builder` will
 417 be used for all mains, even if there are specific switches
 418 specified for one or several mains.
 419
 420 But the switches from package `Binder` or `Linker` will be
 421 the specific switches for each main, if they are specified.
 422
 423 .. _Library_Project_Files:
 424
 425 Library Project Files
 426 ^^^^^^^^^^^^^^^^^^^^^
 427
 428 When *gnatmake* is invoked with a main project file that is a library
 429 project file, it is not allowed to specify one or more mains on the command
 430 line.
 431
 432 When a library project file is specified, switches `-b` and
 433 `-l` have special meanings.
 434
 435 * `-b` is only allowed for stand-alone libraries. It indicates
 436   to *gnatmake* that *gnatbind* should be invoked for the
 437   library.
 438
 439 * `-l` may be used for all library projects. It indicates
 440   to *gnatmake* that the binder generated file should be compiled
 441   (in the case of a stand-alone library) and that the library should be built.
 442
 443
 444 .. _The_GNAT_Driver_and_Project_Files:
 445
 446 The GNAT Driver and Project Files
 447 ---------------------------------
 448
 449 A number of GNAT tools beyond *gnatmake*
 450 can benefit from project files:
 451
 452 .. only:: PRO or GPL
 453
 454   * *gnatbind*
 455   * *gnatcheck*
 456   * *gnatclean*
 457   * *gnatelim*
 458   * *gnatfind*
 459   * *gnatlink*
 460   * *gnatls*
 461   * *gnatmetric*
 462   * *gnatpp*
 463   * *gnatstub*
 464   * *gnatxref*
 465
 466 .. only:: FSF
 467
 468   * *gnatbind*
 469   * *gnatclean*
 470   * *gnatfind*
 471   * *gnatlink*
 472   * *gnatls*
 473   * *gnatxref*
 474
 475 However, none of these tools can be invoked
 476 directly with a project file switch (*-P*).
 477 They must be invoked through the *gnat* driver.
 478
 479 The *gnat* driver is a wrapper that accepts a number of commands and
 480 calls the corresponding tool. It was designed initially for VMS platforms (to
 481 convert VMS qualifiers to Unix-style switches), but it is now available on all
 482 GNAT platforms.
 483
 484 On non-VMS platforms, the *gnat* driver accepts the following commands
 485 (case insensitive):
 486
 487 .. only:: PRO or GPL
 488
 489   * BIND to invoke *gnatbind*
 490   * CHOP to invoke *gnatchop*
 491   * CLEAN to invoke *gnatclean*
 492   * COMP or COMPILE to invoke the compiler
 493   * ELIM to invoke *gnatelim*
 494   * FIND to invoke *gnatfind*
 495   * KR or KRUNCH to invoke *gnatkr*
 496   * LINK to invoke *gnatlink*
 497   * LS or LIST to invoke *gnatls*
 498   * MAKE to invoke *gnatmake*
 499   * METRIC to invoke *gnatmetric*
 500   * NAME to invoke *gnatname*
 501   * PP or PRETTY to invoke *gnatpp*
 502   * PREP or PREPROCESS to invoke *gnatprep*
 503   * STUB to invoke *gnatstub*
 504   * XREF to invoke *gnatxref*
 505
 506 .. only:: FSF
 507
 508   * BIND to invoke *gnatbind*
 509   * CHOP to invoke *gnatchop*
 510   * CLEAN to invoke *gnatclean*
 511   * COMP or COMPILE to invoke the compiler
 512   * FIND to invoke *gnatfind*
 513   * KR or KRUNCH to invoke *gnatkr*
 514   * LINK to invoke *gnatlink*
 515   * LS or LIST to invoke *gnatls*
 516   * MAKE to invoke *gnatmake*
 517   * NAME to invoke *gnatname*
 518   * PREP or PREPROCESS to invoke *gnatprep*
 519   * XREF to invoke *gnatxref*
 520
 521 Note that the command
 522 *gnatmake -c -f -u* is used to invoke the compiler.
 523
 524 On non-VMS platforms, between *gnat* and the command, two
 525 special switches may be used:
 526
 527 * *-v* to display the invocation of the tool.
 528 * *-dn* to prevent the *gnat* driver from removing
 529   the temporary files it has created. These temporary files are
 530   configuration files and temporary file list files.
 531
 532 The command may be followed by switches and arguments for the invoked
 533 tool.
 534
 535   ::
 536
 537      $ gnat bind -C main.ali
 538      $ gnat ls -a main
 539      $ gnat chop foo.txt
 540
 541 Switches may also be put in text files, one switch per line, and the text
 542 files may be specified with their path name preceded by '@'.
 543
 544   ::
 545
 546      $ gnat bind @args.txt main.ali
 547
 548 In addition, for the following commands the project file related switches
 549 (*-P*, *-X* and *-vPx*) may be used in addition to
 550 the switches of the invoking tool:
 551
 552 .. only:: PRO or GPL
 553
 554    * BIND
 555    * COMP or COMPILE
 556    * FIND
 557    * ELIM
 558    * LS or LIST
 559    * LINK
 560    * METRIC
 561    * PP or PRETTY
 562    * STUB
 563    * XREF
 564
 565 .. only:: FSF
 566
 567    * BIND
 568    * COMP or COMPILE
 569    * FIND
 570    * LS or LIST
 571    * LINK
 572    * XREF
 573
 574 .. only:: PRO or GPL
 575
 576    When GNAT PP or GNAT PRETTY is used with a project file, but with no source
 577    specified on the command line, it invokes *gnatpp* with all
 578    the immediate sources of the specified project file.
 579
 580    When GNAT METRIC is used with a project file, but with no source
 581    specified on the command line, it invokes *gnatmetric*
 582    with all the immediate sources of the specified project file and with
 583    *-d* with the parameter pointing to the object directory
 584    of the project.
 585
 586    In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
 587    a project file, no source is specified on the command line and
 588    switch -U is specified on the command line, then
 589    the underlying tool (gnatpp or
 590    gnatmetric) is invoked for all sources of all projects,
 591    not only for the immediate sources of the main project.
 592    (-U stands for Universal or Union of the project files of the project tree)
 593
 594 For each of the following commands, there is optionally a corresponding
 595 package in the main project.
 596
 597 .. only:: PRO or GPL
 598
 599    * package `Binder` for command BIND (invoking `gnatbind`)
 600    * package `Check` for command CHECK (invoking `gnatcheck`)
 601    * package `Compiler` for command COMP or COMPILE (invoking the compiler)
 602    * package `Cross_Reference` for command XREF (invoking `gnatxref`)
 603    * package `Eliminate` for command ELIM (invoking `gnatelim`)
 604    * package `Finder` for command FIND (invoking `gnatfind`)
 605    * package `Gnatls` for command LS or LIST (invoking `gnatls`)
 606    * package `Gnatstub` for command STUB (invoking `gnatstub`)
 607    * package `Linker` for command LINK (invoking `gnatlink`)
 608    * package `Metrics` for command METRIC (invoking `gnatmetric`)
 609    * package `Pretty_Printer` for command PP or PRETTY (invoking `gnatpp`)
 610
 611 .. only:: FSF
 612
 613    * package `Binder` for command BIND (invoking `gnatbind`)
 614    * package `Compiler` for command COMP or COMPILE (invoking the compiler)
 615    * package `Cross_Reference` for command XREF (invoking `gnatxref`)
 616    * package `Finder` for command FIND (invoking `gnatfind`)
 617    * package `Gnatls` for command LS or LIST (invoking `gnatls`)
 618    * package `Linker` for command LINK (invoking `gnatlink`)
 619
 620 Package `Gnatls` has a unique attribute `Switches`,
 621 a simple variable with a string list value. It contains switches
 622 for the invocation of `gnatls`.
 623
 624   .. code-block:: gpr
 625
 626      project Proj1 is
 627         package gnatls is
 628            for Switches
 629                use ("-a",
 630                     "-v");
 631         end gnatls;
 632      end Proj1;
 633
 634 All other packages have two attribute `Switches` and
 635 `Default_Switches`.
 636
 637 `Switches` is an indexed attribute, indexed by the
 638 source file name, that has a string list value: the switches to be
 639 used when the tool corresponding to the package is invoked for the specific
 640 source file.
 641
 642 `Default_Switches` is an attribute,
 643 indexed by  the programming language that has a string list value.
 644 `Default_Switches ("Ada")` contains the
 645 switches for the invocation of the tool corresponding
 646 to the package, except if a specific `Switches` attribute
 647 is specified for the source file.
 648
 649   .. code-block:: gpr
 650
 651      project Proj is
 652
 653         for Source_Dirs use ("");
 654
 655         package gnatls is
 656            for Switches use
 657                ("-a",
 658                 "-v");
 659         end gnatls;
 660
 661         package Compiler is
 662            for Default_Switches ("Ada")
 663                use ("-gnatv",
 664                     "-gnatwa");
 665         end Binder;
 666
 667         package Binder is
 668            for Default_Switches ("Ada")
 669                use ("-C",
 670                     "-e");
 671         end Binder;
 672
 673         package Linker is
 674            for Default_Switches ("Ada")
 675                use ("-C");
 676            for Switches ("main.adb")
 677                use ("-C",
 678                     "-v",
 679                     "-v");
 680         end Linker;
 681
 682         package Finder is
 683            for Default_Switches ("Ada")
 684                 use ("-a",
 685                      "-f");
 686         end Finder;
 687
 688         package Cross_Reference is
 689            for Default_Switches ("Ada")
 690                use ("-a",
 691                     "-f",
 692                     "-d",
 693                     "-u");
 694         end Cross_Reference;
 695      end Proj;
 696
 697 With the above project file, commands such as
 698
 699   ::
 700
 701      $ gnat comp -Pproj main
 702      $ gnat ls -Pproj main
 703      $ gnat xref -Pproj main
 704      $ gnat bind -Pproj main.ali
 705      $ gnat link -Pproj main.ali
 706
 707 will set up the environment properly and invoke the tool with the switches
 708 found in the package corresponding to the tool:
 709 `Default_Switches ("Ada")` for all tools,
 710 except `Switches ("main.adb")`
 711 for `gnatlink`.
 712
 713 .. only:: PRO or GPL
 714
 715    It is also possible to invoke some of the tools,
 716    (`gnatcheck`,
 717    `gnatmetric`,
 718    and `gnatpp`)
 719    on a set of project units thanks to the combination of the switches
 720    *-P*, *-U* and possibly the main unit when one is interested
 721    in its closure. For instance,
 722
 723      ::
 724
 725         $ gnat metric -Pproj
 726
 727    will compute the metrics for all the immediate units of project `proj`.
 728
 729      ::
 730
 731         $ gnat metric -Pproj -U
 732
 733    will compute the metrics for all the units of the closure of projects
 734    rooted at `proj`.
 735
 736      ::
 737
 738         $ gnat metric -Pproj -U main_unit
 739
 740    will compute the metrics for the closure of units rooted at
 741    `main_unit`. This last possibility relies implicitly
 742    on *gnatbind*'s option *-R*. But if the argument files for the
 743    tool invoked by the *gnat* driver are explicitly  specified
 744    either directly or through the tool *-files* option, then the tool
 745    is called only for these explicitly specified files.