1.. _GNAT_Utility_Programs: 2 3********************* 4GNAT Utility Programs 5********************* 6 7This chapter describes a number of utility programs: 8 9.. only:: PRO or GPL 10 11 * :ref:`The_File_Cleanup_Utility_gnatclean` 12 * :ref:`The_GNAT_Library_Browser_gnatls` 13 * :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind` 14 * :ref:`The_Ada_to_HTML_Converter_gnathtml` 15 * :ref:`The_Ada-to-XML_Converter_gnat2xml` 16 * :ref:`The_Program_Property_Verifier_gnatcheck` 17 * :ref:`The_GNAT_Metrics_Tool_gnatmetric` 18 * :ref:`The_GNAT_Pretty-Printer_gnatpp` 19 * :ref:`The_Body_Stub_Generator_gnatstub` 20 * :ref:`The_Unit_Test_Generator_gnattest` 21 22.. only:: FSF 23 24 * :ref:`The_File_Cleanup_Utility_gnatclean` 25 * :ref:`The_GNAT_Library_Browser_gnatls` 26 * :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind` 27 * :ref:`The_Ada_to_HTML_Converter_gnathtml` 28 29Other GNAT utilities are described elsewhere in this manual: 30 31* :ref:`Handling_Arbitrary_File_Naming_Conventions_with_gnatname` 32* :ref:`File_Name_Krunching_with_gnatkr` 33* :ref:`Renaming_Files_with_gnatchop` 34* :ref:`Preprocessing_with_gnatprep` 35 36 37.. _The_File_Cleanup_Utility_gnatclean: 38 39The File Cleanup Utility *gnatclean* 40==================================== 41 42.. index:: File cleanup tool 43.. index:: gnatclean 44 45`gnatclean` is a tool that allows the deletion of files produced by the 46compiler, binder and linker, including ALI files, object files, tree files, 47expanded source files, library files, interface copy source files, binder 48generated files and executable files. 49 50.. _Running_gnatclean: 51 52Running `gnatclean` 53------------------- 54 55The `gnatclean` command has the form: 56 57 :: 58 59 $ gnatclean switches `names` 60 61where `names` is a list of source file names. Suffixes :file:`.ads` and 62:file:`adb` may be omitted. If a project file is specified using switch 63:samp:`-P`, then `names` may be completely omitted. 64 65In normal mode, `gnatclean` delete the files produced by the compiler and, 66if switch `-c` is not specified, by the binder and 67the linker. In informative-only mode, specified by switch 68`-n`, the list of files that would have been deleted in 69normal mode is listed, but no file is actually deleted. 70 71 72.. _Switches_for_gnatclean: 73 74Switches for `gnatclean` 75------------------------ 76 77`gnatclean` recognizes the following switches: 78 79.. index:: --version (gnatclean) 80 81:samp:`--version` 82 Display Copyright and version, then exit disregarding all other options. 83 84.. index:: --help (gnatclean) 85 86:samp:`--help` 87 If *--version* was not used, display usage, then exit disregarding 88 all other options. 89 90:samp:`--subdirs={subdir}` 91 Actual object directory of each project file is the subdirectory subdir of the 92 object directory specified or defaulted in the project file. 93 94:samp:`--unchecked-shared-lib-imports` 95 By default, shared library projects are not allowed to import static library 96 projects. When this switch is used on the command line, this restriction is 97 relaxed. 98 99.. index:: -c (gnatclean) 100 101:samp:`-c` 102 Only attempt to delete the files produced by the compiler, not those produced 103 by the binder or the linker. The files that are not to be deleted are library 104 files, interface copy files, binder generated files and executable files. 105 106.. index:: -D (gnatclean) 107 108:samp:`-D {dir}` 109 Indicate that ALI and object files should normally be found in directory `dir`. 110 111.. index:: -F (gnatclean) 112 113:samp:`-F` 114 When using project files, if some errors or warnings are detected during 115 parsing and verbose mode is not in effect (no use of switch 116 -v), then error lines start with the full path name of the project 117 file, rather than its simple file name. 118 119.. index:: -h (gnatclean) 120 121:samp:`-h` 122 Output a message explaining the usage of `gnatclean`. 123 124.. index:: -n (gnatclean) 125 126:samp:`-n` 127 Informative-only mode. Do not delete any files. Output the list of the files 128 that would have been deleted if this switch was not specified. 129 130.. index:: -P (gnatclean) 131 132:samp:`-P{project}` 133 Use project file `project`. Only one such switch can be used. 134 When cleaning a project file, the files produced by the compilation of the 135 immediate sources or inherited sources of the project files are to be 136 deleted. This is not depending on the presence or not of executable names 137 on the command line. 138 139.. index:: -q (gnatclean) 140 141:samp:`-q` 142 Quiet output. If there are no errors, do not output anything, except in 143 verbose mode (switch -v) or in informative-only mode 144 (switch -n). 145 146.. index:: -r (gnatclean) 147 148:samp:`-r` 149 When a project file is specified (using switch -P), 150 clean all imported and extended project files, recursively. If this switch 151 is not specified, only the files related to the main project file are to be 152 deleted. This switch has no effect if no project file is specified. 153 154.. index:: -v (gnatclean) 155 156:samp:`-v` 157 Verbose mode. 158 159.. index:: -vP (gnatclean) 160 161:samp:`-vP{x}` 162 Indicates the verbosity of the parsing of GNAT project files. 163 :ref:`Switches_Related_to_Project_Files`. 164 165.. index:: -X (gnatclean) 166 167:samp:`-X{name}={value}` 168 Indicates that external variable `name` has the value `value`. 169 The Project Manager will use this value for occurrences of 170 `external(name)` when parsing the project file. 171 :ref:`Switches_Related_to_Project_Files`. 172 173.. index:: -aO (gnatclean) 174 175:samp:`-aO{dir}` 176 When searching for ALI and object files, look in directory `dir`. 177 178.. index:: -I (gnatclean) 179 180:samp:`-I{dir}` 181 Equivalent to :samp:`-aO{dir}`. 182 183.. index:: -I- (gnatclean) 184 185.. index:: Source files, suppressing search 186 187:samp:`-I-` 188 Do not look for ALI or object files in the directory 189 where `gnatclean` was invoked. 190 191 192 193.. _The_GNAT_Library_Browser_gnatls: 194 195The GNAT Library Browser `gnatls` 196================================= 197 198.. index:: Library browser 199.. index:: ! gnatls 200 201`gnatls` is a tool that outputs information about compiled 202units. It gives the relationship between objects, unit names and source 203files. It can also be used to check the source dependencies of a unit 204as well as various characteristics. 205 206Note: to invoke `gnatls` with a project file, use the `gnat` 207driver (see :ref:`The_GNAT_Driver_and_Project_Files`). 208 209.. _Running_gnatls: 210 211Running `gnatls` 212---------------- 213 214The `gnatls` command has the form 215 216 :: 217 218 $ gnatls switches `object_or_ali_file` 219 220The main argument is the list of object or :file:`ali` files 221(see :ref:`The_Ada_Library_Information_Files`) 222for which information is requested. 223 224In normal mode, without additional option, `gnatls` produces a 225four-column listing. Each line represents information for a specific 226object. The first column gives the full path of the object, the second 227column gives the name of the principal unit in this object, the third 228column gives the status of the source and the fourth column gives the 229full path of the source representing this unit. 230Here is a simple example of use: 231 232 233 :: 234 235 $ gnatls *.o 236 ./demo1.o demo1 DIF demo1.adb 237 ./demo2.o demo2 OK demo2.adb 238 ./hello.o h1 OK hello.adb 239 ./instr-child.o instr.child MOK instr-child.adb 240 ./instr.o instr OK instr.adb 241 ./tef.o tef DIF tef.adb 242 ./text_io_example.o text_io_example OK text_io_example.adb 243 ./tgef.o tgef DIF tgef.adb 244 245The first line can be interpreted as follows: the main unit which is 246contained in 247object file :file:`demo1.o` is demo1, whose main source is in 248:file:`demo1.adb`. Furthermore, the version of the source used for the 249compilation of demo1 has been modified (DIF). Each source file has a status 250qualifier which can be: 251 252*OK (unchanged)* 253 The version of the source file used for the compilation of the 254 specified unit corresponds exactly to the actual source file. 255 256*MOK (slightly modified)* 257 The version of the source file used for the compilation of the 258 specified unit differs from the actual source file but not enough to 259 require recompilation. If you use gnatmake with the qualifier 260 *-m (minimal recompilation)*, a file marked 261 MOK will not be recompiled. 262 263*DIF (modified)* 264 No version of the source found on the path corresponds to the source 265 used to build this object. 266 267*??? (file not found)* 268 No source file was found for this unit. 269 270*HID (hidden, unchanged version not first on PATH)* 271 The version of the source that corresponds exactly to the source used 272 for compilation has been found on the path but it is hidden by another 273 version of the same source that has been modified. 274 275 276.. _Switches_for_gnatls: 277 278Switches for `gnatls` 279--------------------- 280 281`gnatls` recognizes the following switches: 282 283 284.. index:: --version (gnatls) 285 286:samp:`--version` 287 Display Copyright and version, then exit disregarding all other options. 288 289 290.. index:: --help (gnatls) 291 292:samp:`*--help` 293 If *--version* was not used, display usage, then exit disregarding 294 all other options. 295 296 297.. index:: -a (gnatls) 298 299:samp:`-a` 300 Consider all units, including those of the predefined Ada library. 301 Especially useful with *-d*. 302 303 304.. index:: -d (gnatls) 305 306:samp:`-d` 307 List sources from which specified units depend on. 308 309 310.. index:: -h (gnatls) 311 312:samp:`-h` 313 Output the list of options. 314 315 316.. index:: -o (gnatls) 317 318:samp:`-o` 319 Only output information about object files. 320 321 322.. index:: -s (gnatls) 323 324:samp:`-s` 325 Only output information about source files. 326 327 328.. index:: -u (gnatls) 329 330:samp:`-u` 331 Only output information about compilation units. 332 333 334.. index:: -files (gnatls) 335 336:samp:`-files={file}` 337 Take as arguments the files listed in text file `file`. 338 Text file `file` may contain empty lines that are ignored. 339 Each nonempty line should contain the name of an existing file. 340 Several such switches may be specified simultaneously. 341 342 343.. index:: -aO (gnatls) 344 345.. index:: -aI (gnatls) 346 347.. index:: -I (gnatls) 348 349.. index:: -I- (gnatls) 350 351:samp:`-aO{dir}`, :samp:`-aI{dir}`, :samp:`-I{dir}`, :samp:`-I-`, :samp:`-nostdinc` 352 Source path manipulation. Same meaning as the equivalent *gnatmake* 353 flags (:ref:`Switches_for_gnatmake`). 354 355 356.. index:: -aP (gnatls) 357 358:samp:`-aP{dir}` 359 Add `dir` at the beginning of the project search dir. 360 361 362.. index:: --RTS (gnatls) 363 364:samp:`--RTS={rts-path}`` 365 Specifies the default location of the runtime library. Same meaning as the 366 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). 367 368 369.. index:: -v (gnatls) 370 371:samp:`-v` 372 Verbose mode. Output the complete source, object and project paths. Do not use 373 the default column layout but instead use long format giving as much as 374 information possible on each requested units, including special 375 characteristics such as: 376 377 * *Preelaborable*: The unit is preelaborable in the Ada sense. 378 379 * *No_Elab_Code*: No elaboration code has been produced by the compiler for this unit. 380 381 * *Pure*: The unit is pure in the Ada sense. 382 383 * *Elaborate_Body*: The unit contains a pragma Elaborate_Body. 384 385 * *Remote_Types*: The unit contains a pragma Remote_Types. 386 387 * *Shared_Passive*: The unit contains a pragma Shared_Passive. 388 389 * *Predefined*: This unit is part of the predefined environment and cannot be modified 390 by the user. 391 392 * *Remote_Call_Interface*: The unit contains a pragma Remote_Call_Interface. 393 394 395.. _Example_of_gnatls_Usage: 396 397Example of `gnatls` Usage 398------------------------- 399 400Example of using the verbose switch. Note how the source and 401object paths are affected by the -I switch. 402 403 :: 404 405 $ gnatls -v -I.. demo1.o 406 407 GNATLS 5.03w (20041123-34) 408 Copyright 1997-2004 Free Software Foundation, Inc. 409 410 Source Search Path: 411 <Current_Directory> 412 ../ 413 /home/comar/local/adainclude/ 414 415 Object Search Path: 416 <Current_Directory> 417 ../ 418 /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ 419 420 Project Search Path: 421 <Current_Directory> 422 /home/comar/local/lib/gnat/ 423 424 ./demo1.o 425 Unit => 426 Name => demo1 427 Kind => subprogram body 428 Flags => No_Elab_Code 429 Source => demo1.adb modified 430 431The following is an example of use of the dependency list. 432Note the use of the -s switch 433which gives a straight list of source files. This can be useful for 434building specialized scripts. 435 436 :: 437 438 $ gnatls -d demo2.o 439 ./demo2.o demo2 OK demo2.adb 440 OK gen_list.ads 441 OK gen_list.adb 442 OK instr.ads 443 OK instr-child.ads 444 445 $ gnatls -d -s -a demo1.o 446 demo1.adb 447 /home/comar/local/adainclude/ada.ads 448 /home/comar/local/adainclude/a-finali.ads 449 /home/comar/local/adainclude/a-filico.ads 450 /home/comar/local/adainclude/a-stream.ads 451 /home/comar/local/adainclude/a-tags.ads 452 gen_list.ads 453 gen_list.adb 454 /home/comar/local/adainclude/gnat.ads 455 /home/comar/local/adainclude/g-io.ads 456 instr.ads 457 /home/comar/local/adainclude/system.ads 458 /home/comar/local/adainclude/s-exctab.ads 459 /home/comar/local/adainclude/s-finimp.ads 460 /home/comar/local/adainclude/s-finroo.ads 461 /home/comar/local/adainclude/s-secsta.ads 462 /home/comar/local/adainclude/s-stalib.ads 463 /home/comar/local/adainclude/s-stoele.ads 464 /home/comar/local/adainclude/s-stratt.ads 465 /home/comar/local/adainclude/s-tasoli.ads 466 /home/comar/local/adainclude/s-unstyp.ads 467 /home/comar/local/adainclude/unchconv.ads 468 469 470.. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind: 471 472The Cross-Referencing Tools `gnatxref` and `gnatfind` 473===================================================== 474 475.. index:: ! gnatxref 476.. index:: ! gnatfind 477 478The compiler generates cross-referencing information (unless 479you set the :samp:`-gnatx` switch), which are saved in the :file:`.ali` files. 480This information indicates where in the source each entity is declared and 481referenced. Note that entities in package Standard are not included, but 482entities in all other predefined units are included in the output. 483 484Before using any of these two tools, you need to compile successfully your 485application, so that GNAT gets a chance to generate the cross-referencing 486information. 487 488The two tools `gnatxref` and `gnatfind` take advantage of this 489information to provide the user with the capability to easily locate the 490declaration and references to an entity. These tools are quite similar, 491the difference being that `gnatfind` is intended for locating 492definitions and/or references to a specified entity or entities, whereas 493`gnatxref` is oriented to generating a full report of all 494cross-references. 495 496To use these tools, you must not compile your application using the 497*-gnatx* switch on the *gnatmake* command line 498(see :ref:`The_GNAT_Make_Program_gnatmake`). Otherwise, cross-referencing 499information will not be generated. 500 501Note: to invoke `gnatxref` or `gnatfind` with a project file, 502use the `gnat` driver (see :ref:`The_GNAT_Driver_and_Project_Files`). 503 504.. _gnatxref_Switches: 505 506`gnatxref` Switches 507------------------- 508 509The command invocation for `gnatxref` is: 510 511 :: 512 513 $ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...] 514 515where 516 517*sourcefile1* [, *sourcefile2* ...] 518 identify the source files for which a report is to be generated. The 519 'with'ed units will be processed too. You must provide at least one file. 520 521 These file names are considered to be regular expressions, so for instance 522 specifying :file:`source\*.adb` is the same as giving every file in the current 523 directory whose name starts with :file:`source` and whose extension is 524 :file:`adb`. 525 526 You shouldn't specify any directory name, just base names. *gnatxref* 527 and *gnatfind* will be able to locate these files by themselves using 528 the source path. If you specify directories, no result is produced. 529 530The following switches are available for *gnatxref*: 531 532 533.. index:: --version (gnatxref) 534 535:samp:`-version` 536 Display Copyright and version, then exit disregarding all other options. 537 538 539.. index:: --help (gnatxref) 540 541:samp:`-help` 542 If *--version* was not used, display usage, then exit disregarding 543 all other options. 544 545 546.. index:: -a (gnatxref) 547 548:samp:`a` 549 If this switch is present, `gnatfind` and `gnatxref` will parse 550 the read-only files found in the library search path. Otherwise, these files 551 will be ignored. This option can be used to protect Gnat sources or your own 552 libraries from being parsed, thus making `gnatfind` and `gnatxref` 553 much faster, and their output much smaller. Read-only here refers to access 554 or permissions status in the file system for the current user. 555 556 557.. index:: -aIDIR (gnatxref) 558 559:samp:`aI{DIR}` 560 When looking for source files also look in directory DIR. The order in which 561 source file search is undertaken is the same as for *gnatmake*. 562 563 564.. index:: -aODIR (gnatxref) 565 566:samp:`aO{DIR}` 567 When searching for library and object files, look in directory 568 DIR. The order in which library files are searched is the same as for 569 *gnatmake*. 570 571 572.. index:: -nostdinc (gnatxref) 573 574:samp:`nostdinc` 575 Do not look for sources in the system default directory. 576 577 578.. index:: -nostdlib (gnatxref) 579 580:samp:`nostdlib` 581 Do not look for library files in the system default directory. 582 583 584.. index:: --ext (gnatxref) 585 586:samp:`-ext={extension}` 587 Specify an alternate ali file extension. The default is `ali` and other 588 extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*) 589 may be specified via this switch. Note that if this switch overrides the 590 default, which means that only the new extension will be considered. 591 592 593.. index:: --RTS (gnatxref) 594 595:samp:`-RTS={rts-path}` 596 Specifies the default location of the runtime library. Same meaning as the 597 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). 598 599 600.. index:: -d (gnatxref) 601 602:samp:`d` 603 If this switch is set `gnatxref` will output the parent type 604 reference for each matching derived types. 605 606 607.. index:: -f (gnatxref) 608 609:samp:`f` 610 If this switch is set, the output file names will be preceded by their 611 directory (if the file was found in the search path). If this switch is 612 not set, the directory will not be printed. 613 614 615.. index:: -g (gnatxref) 616 617:samp:`g` 618 If this switch is set, information is output only for library-level 619 entities, ignoring local entities. The use of this switch may accelerate 620 `gnatfind` and `gnatxref`. 621 622 623.. index:: -IDIR (gnatxref) 624 625:samp:`I{DIR}` 626 Equivalent to :samp:`-aODIR -aIDIR`. 627 628 629.. index:: -pFILE (gnatxref) 630 631:samp:`p{FILE}` 632 Specify a project file to use :ref:`GNAT_Project_Manager`. 633 If you need to use the :file:`.gpr` 634 project files, you should use gnatxref through the GNAT driver 635 (*gnat xref -Pproject*). 636 637 By default, `gnatxref` and `gnatfind` will try to locate a 638 project file in the current directory. 639 640 If a project file is either specified or found by the tools, then the content 641 of the source directory and object directory lines are added as if they 642 had been specified respectively by :samp:`-aI` 643 and :samp:`-aO`. 644 645:samp:`u` 646 Output only unused symbols. This may be really useful if you give your 647 main compilation unit on the command line, as `gnatxref` will then 648 display every unused entity and 'with'ed package. 649 650 651:samp:`v` 652 Instead of producing the default output, `gnatxref` will generate a 653 :file:`tags` file that can be used by vi. For examples how to use this 654 feature, see :ref:`Examples_of_gnatxref_Usage`. The tags file is output 655 to the standard output, thus you will have to redirect it to a file. 656 657All these switches may be in any order on the command line, and may even 658appear after the file names. They need not be separated by spaces, thus 659you can say :samp:`gnatxref -ag` instead of :samp:`gnatxref -a -g`. 660 661.. _gnatfind_Switches: 662 663`gnatfind` Switches 664------------------- 665 666The command invocation for `gnatfind` is: 667 668 :: 669 670 $ gnatfind [`switches`] `pattern`[:`sourcefile`[:`line`[:`column`]]] 671 [`file1` `file2` ...] 672 673with the following iterpretation of the command arguments: 674 675*pattern* 676 An entity will be output only if it matches the regular expression found 677 in `pattern`, see :ref:`Regular_Expressions_in_gnatfind_and_gnatxref`. 678 679 Omitting the pattern is equivalent to specifying ``*``, which 680 will match any entity. Note that if you do not provide a pattern, you 681 have to provide both a sourcefile and a line. 682 683 Entity names are given in Latin-1, with uppercase/lowercase equivalence 684 for matching purposes. At the current time there is no support for 685 8-bit codes other than Latin-1, or for wide characters in identifiers. 686 687*sourcefile* 688 `gnatfind` will look for references, bodies or declarations 689 of symbols referenced in :file:`sourcefile`, at line `line` 690 and column `column`. See :ref:`Examples_of_gnatfind_Usage` 691 for syntax examples. 692 693*line* 694 A decimal integer identifying the line number containing 695 the reference to the entity (or entities) to be located. 696 697 698*column* 699 A decimal integer identifying the exact location on the 700 line of the first character of the identifier for the 701 entity reference. Columns are numbered from 1. 702 703 704*file1 file2 ...* 705 The search will be restricted to these source files. If none are given, then 706 the search will be conducted for every library file in the search path. 707 These files must appear only after the pattern or sourcefile. 708 709 These file names are considered to be regular expressions, so for instance 710 specifying :file:`source\*.adb` is the same as giving every file in the current 711 directory whose name starts with :file:`source` and whose extension is 712 :file:`adb`. 713 714 The location of the spec of the entity will always be displayed, even if it 715 isn't in one of :file:`file1`, :file:`file2`, ... The 716 occurrences of the entity in the separate units of the ones given on the 717 command line will also be displayed. 718 719 Note that if you specify at least one file in this part, `gnatfind` may 720 sometimes not be able to find the body of the subprograms. 721 722 723At least one of 'sourcefile' or 'pattern' has to be present on 724the command line. 725 726The following switches are available: 727 728.. index:: --version (gnatfind) 729 730:samp:`--version` 731 Display Copyright and version, then exit disregarding all other options. 732 733 734.. index:: --help (gnatfind) 735 736:samp:`-help` 737 If *--version* was not used, display usage, then exit disregarding 738 all other options. 739 740 741.. index:: -a (gnatfind) 742 743:samp:`a` 744 If this switch is present, `gnatfind` and `gnatxref` will parse 745 the read-only files found in the library search path. Otherwise, these files 746 will be ignored. This option can be used to protect Gnat sources or your own 747 libraries from being parsed, thus making `gnatfind` and `gnatxref` 748 much faster, and their output much smaller. Read-only here refers to access 749 or permission status in the file system for the current user. 750 751 752.. index:: -aIDIR (gnatfind) 753 754:samp:`aI{DIR}` 755 When looking for source files also look in directory DIR. The order in which 756 source file search is undertaken is the same as for *gnatmake*. 757 758 759.. index:: -aODIR (gnatfind) 760 761:samp:`aO{DIR}` 762 When searching for library and object files, look in directory 763 DIR. The order in which library files are searched is the same as for 764 *gnatmake*. 765 766 767.. index:: -nostdinc (gnatfind) 768 769:samp:`nostdinc` 770 Do not look for sources in the system default directory. 771 772 773.. index:: -nostdlib (gnatfind) 774 775:samp:`nostdlib` 776 Do not look for library files in the system default directory. 777 778 779.. index:: --ext (gnatfind) 780 781:samp:`-ext={extension}` 782 Specify an alternate ali file extension. The default is `ali` and other 783 extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*) 784 may be specified via this switch. Note that if this switch overrides the 785 default, which means that only the new extension will be considered. 786 787 788.. index:: --RTS (gnatfind) 789 790:samp:`-RTS={rts-path}` 791 Specifies the default location of the runtime library. Same meaning as the 792 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). 793 794 795.. index:: -d (gnatfind) 796 797:samp:`d` 798 If this switch is set, then `gnatfind` will output the parent type 799 reference for each matching derived types. 800 801 802.. index:: -e (gnatfind) 803 804:samp:`e` 805 By default, `gnatfind` accept the simple regular expression set for 806 `pattern`. If this switch is set, then the pattern will be 807 considered as full Unix-style regular expression. 808 809 810.. index:: -f (gnatfind) 811 812:samp:`f` 813 If this switch is set, the output file names will be preceded by their 814 directory (if the file was found in the search path). If this switch is 815 not set, the directory will not be printed. 816 817 818.. index:: -g (gnatfind) 819 820:samp:`g` 821 If this switch is set, information is output only for library-level 822 entities, ignoring local entities. The use of this switch may accelerate 823 `gnatfind` and `gnatxref`. 824 825 826.. index:: -IDIR (gnatfind) 827 828:samp:`I{DIR}` 829 Equivalent to :samp:`-aODIR -aIDIR`. 830 831 832.. index:: -pFILE (gnatfind) 833 834:samp:`p{FILE}` 835 Specify a project file (:ref:`GNAT_Project_Manager`) to use. 836 By default, `gnatxref` and `gnatfind` will try to locate a 837 project file in the current directory. 838 839 If a project file is either specified or found by the tools, then the content 840 of the source directory and object directory lines are added as if they 841 had been specified respectively by :samp:`-aI` and 842 :samp:`-aO`. 843 844 845.. index:: -r (gnatfind) 846 847:samp:`r` 848 By default, `gnatfind` will output only the information about the 849 declaration, body or type completion of the entities. If this switch is 850 set, the `gnatfind` will locate every reference to the entities in 851 the files specified on the command line (or in every file in the search 852 path if no file is given on the command line). 853 854 855.. index:: -s (gnatfind) 856 857:samp:`s` 858 If this switch is set, then `gnatfind` will output the content 859 of the Ada source file lines were the entity was found. 860 861 862.. index:: -t (gnatfind) 863 864:samp:`t` 865 If this switch is set, then `gnatfind` will output the type hierarchy for 866 the specified type. It act like -d option but recursively from parent 867 type to parent type. When this switch is set it is not possible to 868 specify more than one file. 869 870 871All these switches may be in any order on the command line, and may even 872appear after the file names. They need not be separated by spaces, thus 873you can say :samp:`gnatxref -ag` instead of 874:samp:`gnatxref -a -g`. 875 876As stated previously, gnatfind will search in every directory in the 877search path. You can force it to look only in the current directory if 878you specify `*` at the end of the command line. 879 880.. _Project_Files_for_gnatxref_and_gnatfind: 881 882Project Files for *gnatxref* and *gnatfind* 883------------------------------------------- 884 885Project files allow a programmer to specify how to compile its 886application, where to find sources, etc. These files are used 887primarily by GPS, but they can also be used 888by the two tools `gnatxref` and `gnatfind`. 889 890A project file name must end with :file:`.gpr`. If a single one is 891present in the current directory, then `gnatxref` and `gnatfind` will 892extract the information from it. If multiple project files are found, none of 893them is read, and you have to use the :samp:`-p` switch to specify the one 894you want to use. 895 896The following lines can be included, even though most of them have default 897values which can be used in most cases. 898The lines can be entered in any order in the file. 899Except for :file:`src_dir` and :file:`obj_dir`, you can only have one instance of 900each line. If you have multiple instances, only the last one is taken into 901account. 902 903* *src_dir=DIR* 904 [default: `"./"`]. 905 Specifies a directory where to look for source files. Multiple `src_dir` 906 lines can be specified and they will be searched in the order they 907 are specified. 908 909 910* *obj_dir=DIR* 911 [default: `"./"`]. 912 Specifies a directory where to look for object and library files. Multiple 913 `obj_dir` lines can be specified, and they will be searched in the order 914 they are specified 915 916 917* *comp_opt=SWITCHES* 918 [default: `""`]. 919 Creates a variable which can be referred to subsequently by using 920 the `${comp_opt}` notation. This is intended to store the default 921 switches given to *gnatmake* and *gcc*. 922 923 924* *bind_opt=SWITCHES* 925 [default: `""`]. 926 Creates a variable which can be referred to subsequently by using 927 the :samp:`${bind_opt}` notation. This is intended to store the default 928 switches given to *gnatbind*. 929 930 931* *link_opt=SWITCHES* 932 [default: `""`]. 933 Creates a variable which can be referred to subsequently by using 934 the :samp:`${link_opt}` notation. This is intended to store the default 935 switches given to *gnatlink*. 936 937 938* *main=EXECUTABLE* 939 [default: `""`]. 940 Specifies the name of the executable for the application. This variable can 941 be referred to in the following lines by using the :samp:`{${main}` notation. 942 943 944* *comp_cmd=COMMAND* 945 [default: `"gcc -c -I${src_dir} -g -gnatq"`]. 946 Specifies the command used to compile a single file in the application. 947 948 949* *make_cmd=COMMAND* 950 [default: `"gnatmake ${main} -aI${src_dir} 951 -aO${obj_dir} -g -gnatq -cargs ${comp_opt} 952 -bargs ${bind_opt} -largs ${link_opt}"`]. 953 Specifies the command used to recompile the whole application. 954 955 956* *run_cmd=COMMAND* 957 [default: `"${main}"`]. 958 Specifies the command used to run the application. 959 960 961* *debug_cmd=COMMAND* 962 [default: `"gdb ${main}"`]. 963 Specifies the command used to debug the application 964 965 966*gnatxref* and *gnatfind* only take into account the 967`src_dir` and `obj_dir` lines, and ignore the others. 968 969 970.. _Regular_Expressions_in_gnatfind_and_gnatxref: 971 972Regular Expressions in `gnatfind` and `gnatxref` 973------------------------------------------------ 974 975As specified in the section about *gnatfind*, the pattern can be a 976regular expression. Two kinds of regular expressions 977are recognized: 978 979* *Globbing pattern* 980 These are the most common regular expression. They are the same as are 981 generally used in a Unix shell command line, or in a DOS session. 982 983 Here is a more formal grammar: 984 985 :: 986 987 regexp ::= term 988 term ::= elmt -- matches elmt 989 term ::= elmt elmt -- concatenation (elmt then elmt) 990 term ::= * -- any string of 0 or more characters 991 term ::= ? -- matches any character 992 term ::= [char {char}] -- matches any character listed 993 term ::= [char - char] -- matches any character in range 994 995* *Full regular expression* 996 The second set of regular expressions is much more powerful. This is the 997 type of regular expressions recognized by utilities such as :samp:`grep`. 998 999 The following is the form of a regular expression, expressed in same BNF 1000 style as is found in the Ada Reference Manual: 1001 1002 :: 1003 1004 regexp ::= term {| term} -- alternation (term or term ...) 1005 1006 term ::= item {item} -- concatenation (item then item) 1007 1008 item ::= elmt -- match elmt 1009 item ::= elmt * -- zero or more elmt's 1010 item ::= elmt + -- one or more elmt's 1011 item ::= elmt ? -- matches elmt or nothing 1012 1013 elmt ::= nschar -- matches given character 1014 elmt ::= [nschar {nschar}] -- matches any character listed 1015 elmt ::= [^ nschar {nschar}] -- matches any character not listed 1016 elmt ::= [char - char] -- matches chars in given range 1017 elmt ::= \\ char -- matches given character 1018 elmt ::= . -- matches any single character 1019 elmt ::= ( regexp ) -- parens used for grouping 1020 1021 char ::= any character, including special characters 1022 nschar ::= any character except ()[].*+?^ 1023 1024 Here are a few examples: 1025 1026 ``abcde|fghi`` 1027 will match any of the two strings :samp:`abcde` and :samp:`fghi`, 1028 1029 ``abc*d`` 1030 will match any string like ``abd``, ``abcd``, ``abccd``, 1031 ``abcccd``, and so on, 1032 1033 ``[a-z]+`` 1034 will match any string which has only lowercase characters in it (and at 1035 least one character. 1036 1037 1038.. _Examples_of_gnatxref_Usage: 1039 1040Examples of `gnatxref` Usage 1041---------------------------- 1042 1043General Usage 1044^^^^^^^^^^^^^ 1045 1046For the following examples, we will consider the following units: 1047 1048 .. code-block:: ada 1049 1050 main.ads: 1051 1: with Bar; 1052 2: package Main is 1053 3: procedure Foo (B : in Integer); 1054 4: C : Integer; 1055 5: private 1056 6: D : Integer; 1057 7: end Main; 1058 1059 main.adb: 1060 1: package body Main is 1061 2: procedure Foo (B : in Integer) is 1062 3: begin 1063 4: C := B; 1064 5: D := B; 1065 6: Bar.Print (B); 1066 7: Bar.Print (C); 1067 8: end Foo; 1068 9: end Main; 1069 1070 bar.ads: 1071 1: package Bar is 1072 2: procedure Print (B : Integer); 1073 3: end bar; 1074 1075The first thing to do is to recompile your application (for instance, in 1076that case just by doing a ``gnatmake main``, so that GNAT generates 1077the cross-referencing information. 1078You can then issue any of the following commands: 1079 1080 * ``gnatxref main.adb`` 1081 `gnatxref` generates cross-reference information for main.adb 1082 and every unit 'with'ed by main.adb. 1083 1084 The output would be: 1085 1086 :: 1087 1088 B Type: Integer 1089 Decl: bar.ads 2:22 1090 B Type: Integer 1091 Decl: main.ads 3:20 1092 Body: main.adb 2:20 1093 Ref: main.adb 4:13 5:13 6:19 1094 Bar Type: Unit 1095 Decl: bar.ads 1:9 1096 Ref: main.adb 6:8 7:8 1097 main.ads 1:6 1098 C Type: Integer 1099 Decl: main.ads 4:5 1100 Modi: main.adb 4:8 1101 Ref: main.adb 7:19 1102 D Type: Integer 1103 Decl: main.ads 6:5 1104 Modi: main.adb 5:8 1105 Foo Type: Unit 1106 Decl: main.ads 3:15 1107 Body: main.adb 2:15 1108 Main Type: Unit 1109 Decl: main.ads 2:9 1110 Body: main.adb 1:14 1111 Print Type: Unit 1112 Decl: bar.ads 2:15 1113 Ref: main.adb 6:12 7:12 1114 1115 1116 This shows that the entity `Main` is declared in main.ads, line 2, column 9, 1117 its body is in main.adb, line 1, column 14 and is not referenced any where. 1118 1119 The entity `Print` is declared in bar.ads, line 2, column 15 and it 1120 is referenced in main.adb, line 6 column 12 and line 7 column 12. 1121 1122 1123 * ``gnatxref package1.adb package2.ads`` 1124 `gnatxref` will generates cross-reference information for 1125 package1.adb, package2.ads and any other package 'with'ed by any 1126 of these. 1127 1128 1129Using gnatxref with vi 1130^^^^^^^^^^^^^^^^^^^^^^ 1131 1132`gnatxref` can generate a tags file output, which can be used 1133directly from *vi*. Note that the standard version of *vi* 1134will not work properly with overloaded symbols. Consider using another 1135free implementation of *vi*, such as *vim*. 1136 1137 :: 1138 1139 $ gnatxref -v gnatfind.adb > tags 1140 1141 1142The following command will generate the tags file for `gnatfind` itself 1143(if the sources are in the search path!): 1144 1145 :: 1146 1147 $ gnatxref -v gnatfind.adb > tags 1148 1149From *vi*, you can then use the command :samp:`:tag {entity}` 1150(replacing `entity` by whatever you are looking for), and vi will 1151display a new file with the corresponding declaration of entity. 1152 1153 1154.. _Examples_of_gnatfind_Usage: 1155 1156Examples of `gnatfind` Usage 1157---------------------------- 1158 1159* ``gnatfind -f xyz:main.adb`` 1160 Find declarations for all entities xyz referenced at least once in 1161 main.adb. The references are search in every library file in the search 1162 path. 1163 1164 The directories will be printed as well (as the ``-f`` 1165 switch is set) 1166 1167 The output will look like: 1168 1169 :: 1170 1171 directory/main.ads:106:14: xyz <= declaration 1172 directory/main.adb:24:10: xyz <= body 1173 directory/foo.ads:45:23: xyz <= declaration 1174 1175 I.e., one of the entities xyz found in main.adb is declared at 1176 line 12 of main.ads (and its body is in main.adb), and another one is 1177 declared at line 45 of foo.ads 1178 1179* ``gnatfind -fs xyz:main.adb`` 1180 This is the same command as the previous one, but `gnatfind` will 1181 display the content of the Ada source file lines. 1182 1183 The output will look like: 1184 1185 :: 1186 1187 directory/main.ads:106:14: xyz <= declaration 1188 procedure xyz; 1189 directory/main.adb:24:10: xyz <= body 1190 procedure xyz is 1191 directory/foo.ads:45:23: xyz <= declaration 1192 xyz : Integer; 1193 1194 This can make it easier to find exactly the location your are looking 1195 for. 1196 1197 1198* ``gnatfind -r "*x*":main.ads:123 foo.adb`` 1199 Find references to all entities containing an x that are 1200 referenced on line 123 of main.ads. 1201 The references will be searched only in main.ads and foo.adb. 1202 1203 1204* ``gnatfind main.ads:123`` 1205 Find declarations and bodies for all entities that are referenced on 1206 line 123 of main.ads. 1207 1208 This is the same as ``gnatfind "*":main.adb:123``` 1209 1210* ``gnatfind mydir/main.adb:123:45`` 1211 Find the declaration for the entity referenced at column 45 in 1212 line 123 of file main.adb in directory mydir. Note that it 1213 is usual to omit the identifier name when the column is given, 1214 since the column position identifies a unique reference. 1215 1216 The column has to be the beginning of the identifier, and should not 1217 point to any character in the middle of the identifier. 1218 1219 1220.. _The_Ada_to_HTML_Converter_gnathtml: 1221 1222The Ada to HTML Converter `gnathtml` 1223==================================== 1224 1225.. index:: ! gnathtml 1226 1227*gnathtml* is a Perl script that allows Ada source files to be browsed using 1228standard Web browsers. For installation information, see :ref:`Installing_gnathtml`. 1229 1230Ada reserved keywords are highlighted in a bold font and Ada comments in 1231a blue font. Unless your program was compiled with the gcc *-gnatx* 1232switch to suppress the generation of cross-referencing information, user 1233defined variables and types will appear in a different color; you will 1234be able to click on any identifier and go to its declaration. 1235 1236.. _Invoking_gnathtml: 1237 1238Invoking *gnathtml* 1239------------------- 1240 1241The command line is as follows: 1242 1243 :: 1244 1245 $ perl gnathtml.pl [`switches`] `ada-files` 1246 1247You can specify as many Ada files as you want. `gnathtml` will generate 1248an html file for every ada file, and a global file called :file:`index.htm`. 1249This file is an index of every identifier defined in the files. 1250 1251The following switches are available: 1252 1253.. index:: -83 (gnathtml) 1254 1255:samp:`83` 1256 Only the Ada 83 subset of keywords will be highlighted. 1257 1258.. index:: -cc (gnathtml) 1259 1260:samp:`cc {color}` 1261 This option allows you to change the color used for comments. The default 1262 value is green. The color argument can be any name accepted by html. 1263 1264.. index:: -d (gnathtml) 1265 1266:samp:`d` 1267 If the Ada files depend on some other files (for instance through 1268 `with` clauses, the latter files will also be converted to html. 1269 Only the files in the user project will be converted to html, not the files 1270 in the run-time library itself. 1271 1272.. index:: -D (gnathtml) 1273 1274:samp:`D` 1275 This command is the same as *-d* above, but *gnathtml* will 1276 also look for files in the run-time library, and generate html files for them. 1277 1278.. index:: -ext (gnathtml) 1279 1280:samp:`ext {extension}` 1281 This option allows you to change the extension of the generated HTML files. 1282 If you do not specify an extension, it will default to :file:`htm`. 1283 1284.. index:: -f (gnathtml) 1285 1286:samp:`f` 1287 By default, gnathtml will generate html links only for global entities 1288 ('with'ed units, global variables and types,...). If you specify 1289 *-f* on the command line, then links will be generated for local 1290 entities too. 1291 1292.. index:: -l (gnathtml) 1293 1294:samp:`l {number}` 1295 If this switch is provided and `number` is not 0, then 1296 `gnathtml` will number the html files every `number` line. 1297 1298.. index:: -I (gnathtml) 1299 1300:samp:`I {dir}` 1301 Specify a directory to search for library files (:file:`.ALI` files) and 1302 source files. You can provide several -I switches on the command line, 1303 and the directories will be parsed in the order of the command line. 1304 1305.. index:: -o (gnathtml) 1306 1307:samp:`o {dir}` 1308 Specify the output directory for html files. By default, gnathtml will 1309 saved the generated html files in a subdirectory named :file:`html/`. 1310 1311.. index:: -p (gnathtml) 1312 1313:samp:`p {file}` 1314 If you are using Emacs and the most recent Emacs Ada mode, which provides 1315 a full Integrated Development Environment for compiling, checking, 1316 running and debugging applications, you may use :file:`.gpr` files 1317 to give the directories where Emacs can find sources and object files. 1318 1319 Using this switch, you can tell gnathtml to use these files. 1320 This allows you to get an html version of your application, even if it 1321 is spread over multiple directories. 1322 1323.. index:: -sc (gnathtml) 1324 1325:samp:`sc {color}` 1326 This switch allows you to change the color used for symbol 1327 definitions. 1328 The default value is red. The color argument can be any name accepted by html. 1329 1330.. index:: -t (gnathtml) 1331 1332:samp:`t {file}` 1333 This switch provides the name of a file. This file contains a list of 1334 file names to be converted, and the effect is exactly as though they had 1335 appeared explicitly on the command line. This 1336 is the recommended way to work around the command line length limit on some 1337 systems. 1338 1339.. _Installing_gnathtml: 1340 1341Installing `gnathtml` 1342--------------------- 1343 1344`Perl` needs to be installed on your machine to run this script. 1345`Perl` is freely available for almost every architecture and 1346operating system via the Internet. 1347 1348On Unix systems, you may want to modify the first line of the script 1349`gnathtml`, to explicitly specify where Perl 1350is located. The syntax of this line is: 1351 1352 :: 1353 1354 #!full_path_name_to_perl 1355 1356Alternatively, you may run the script using the following command line: 1357 1358 :: 1359 1360 $ perl gnathtml.pl [`switches`] `files` 1361 1362 1363 1364 1365.. -- +---------------------------------------------------------------------+ 1366.. -- | The following sections are present only in the PRO and GPL editions | 1367.. -- +---------------------------------------------------------------------+ 1368 1369.. only:: PRO or GPL 1370 1371 .. _The_Ada-to-XML_converter_gnat2xml: 1372 1373 The Ada-to-XML converter *gnat2xml* 1374 =================================== 1375 1376 .. index:: ! gnat2xml 1377 .. index:: XML generation 1378 1379 The *gnat2xml* tool is an ASIS-based utility that converts 1380 Ada source code into XML. 1381 1382 .. _Switches_for_*gnat2xml*: 1383 1384 Switches for *gnat2xml* 1385 ----------------------- 1386 1387 *gnat2xml* takes Ada source code as input, and produces XML 1388 that conforms to the schema. 1389 1390 Usage: 1391 1392 :: 1393 1394 $ gnat2xml [options] filenames [-files filename] [-cargs gcc_switches] 1395 1396 Options: 1397 1398 :samp:`--help` 1399 Generate usage information and quit, ignoring all other options 1400 1401 :samp:`-h` 1402 Same as ``--help`` 1403 1404 :samp:`--version` 1405 Print version and quit, ignoring all other options 1406 1407 :samp:`-P{file}` 1408 indicates the name of the project file that describes 1409 the set of sources to be processed. The exact set of argument 1410 sources depends on other options specified, see below. 1411 1412 :samp:`-U` 1413 If a project file is specified and no argument source is explicitly 1414 specified, process all the units of the closure of the argument project. 1415 Otherwise this option has no effect. 1416 1417 :samp:`-U {main_unit}` 1418 If a project file is specified and no argument source 1419 is explicitly specified (either directly or by means of *-files* 1420 option), process the closure of units rooted at `main_unit`. 1421 Otherwise this option has no effect. 1422 1423 :samp:`-X{name}={value}` 1424 Indicates that external variable `name` in 1425 the argument project has the value `value`. Has no effect if no 1426 project is specified as tool argument. 1427 1428 :samp:`--RTS={rts-path}` 1429 Specifies the default location of the runtime 1430 library. Same meaning as the equivalent *gnatmake* flag 1431 (:ref:`Switches_for_gnatmake`). 1432 1433 :samp:`--incremental` 1434 Incremental processing on a per-file basis. Source files are 1435 only processed if they have been modified, or if files they depend 1436 on have been modified. This is similar to the way gnatmake/gprbuild 1437 only compiles files that need to be recompiled. A project file 1438 is required in this mode. 1439 1440 :samp:`-j{n}` 1441 In *--incremental* mode, use `n` *gnat2xml* 1442 processes to perform XML generation in parallel. If `n` is 0, then 1443 the maximum number of parallel tree creations is the number of core 1444 processors on the platform. 1445 1446 :samp:`--output-dir={dir}` 1447 Generate one .xml file for each Ada source file, in 1448 directory :file:`dir`. (Default is to generate the XML to standard 1449 output.) 1450 1451 :samp:`-I{include-dir}` 1452 Directories to search for dependencies. 1453 You can also set the ADA_INCLUDE_PATH environment variable for this. 1454 1455 :samp:`--compact` 1456 Debugging version, with interspersed source, and a more 1457 compact representation of "sloc". This version does not conform 1458 to any schema. 1459 1460 :samp:`--rep-clauses` 1461 generate representation clauses (see :ref:`Generating_Representation_Clauses`). 1462 1463 :samp:`-files={filename}` 1464 The name of a text file containing a list of Ada source files to process 1465 1466 :samp:`-q` 1467 Quiet 1468 1469 :samp:`-v` 1470 Verbose 1471 1472 :samp:`-cargs` ... 1473 Options to pass to gcc 1474 1475 If a project file is specified and no argument source is explicitly 1476 specified, and no *-U* is specified, then the set of processed 1477 sources is all the immediate units of the argument project. 1478 1479 Example: 1480 1481 :: 1482 1483 $ gnat2xml -v -output-dir=xml-files *.ad[sb] 1484 1485 The above will create \*.xml files in the :file:`xml-files` subdirectory. 1486 For example, if there is an Ada package Mumble.Dumble, whose spec and 1487 body source code lives in mumble-dumble.ads and mumble-dumble.adb, 1488 the above will produce xml-files/mumble-dumble.ads.xml and 1489 xml-files/mumble-dumble.adb.xml. 1490 1491 .. _Other_Programs: 1492 1493 Other Programs 1494 -------------- 1495 1496 The distribution includes two other programs that are related to 1497 *gnat2xml*: 1498 1499 *gnat2xsd* is the schema generator, which generates the schema 1500 to standard output, based on the structure of Ada as encoded by 1501 ASIS. You don't need to run *gnat2xsd* in order to use 1502 *gnat2xml*. To generate the schema, type: 1503 1504 1505 :: 1506 1507 $ gnat2xsd > ada-schema.xsd 1508 1509 1510 *gnat2xml* generates XML files that will validate against 1511 :file:`ada-schema.xsd`. 1512 1513 *xml2gnat* is a back-translator that translates the XML back 1514 into Ada source code. The Ada generated by *xml2gnat* has 1515 identical semantics to the original Ada code passed to 1516 *gnat2xml*. It is not textually identical, however --- for 1517 example, no attempt is made to preserve the original indentation. 1518 1519 .. _Structure_of_the_XML: 1520 1521 Structure of the XML 1522 -------------------- 1523 1524 The primary documentation for the structure of the XML generated by 1525 *gnat2xml* is the schema (see *gnat2xsd* above). The 1526 following documentation gives additional details needed to understand 1527 the schema and therefore the XML. 1528 1529 The elements listed under Defining Occurrences, Usage Occurrences, and 1530 Other Elements represent the syntactic structure of the Ada program. 1531 Element names are given in lower case, with the corresponding element 1532 type Capitalized_Like_This. The element and element type names are 1533 derived directly from the ASIS enumeration type Flat_Element_Kinds, 1534 declared in Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_`` 1535 removed. For example, the ASIS enumeration literal 1536 An_Assignment_Statement corresponds to the XML element 1537 assignment_statement of XML type Assignment_Statement. 1538 1539 To understand the details of the schema and the corresponding XML, it is 1540 necessary to understand the ASIS standard, as well as the GNAT-specific 1541 extension to ASIS. 1542 1543 A defining occurrence is an identifier (or character literal or operator 1544 symbol) declared by a declaration. A usage occurrence is an identifier 1545 (or ...) that references such a declared entity. For example, in: 1546 1547 1548 .. code-block:: ada 1549 1550 type T is range 1..10; 1551 X, Y : constant T := 1; 1552 1553 1554 The first 'T' is the defining occurrence of a type. The 'X' is the 1555 defining occurrence of a constant, as is the 'Y', and the second 'T' is 1556 a usage occurrence referring to the defining occurrence of T. 1557 1558 Each element has a 'sloc' (source location), and subelements for each 1559 syntactic subtree, reflecting the Ada grammar as implemented by ASIS. 1560 The types of subelements are as defined in the ASIS standard. For 1561 example, for the right-hand side of an assignment_statement we have 1562 the following comment in asis-statements.ads: 1563 1564 .. code-block:: ada 1565 1566 ------------------------------------------------------------------------------ 1567 -- 18.3 function Assignment_Expression 1568 ------------------------------------------------------------------------------ 1569 1570 function Assignment_Expression 1571 (Statement : Asis.Statement) 1572 return Asis.Expression; 1573 1574 ------------------------------------------------------------------------------ 1575 ... 1576 -- Returns the expression from the right hand side of the assignment. 1577 ... 1578 -- Returns Element_Kinds: 1579 -- An_Expression 1580 1581 1582 The corresponding sub-element of type Assignment_Statement is: 1583 1584 :: 1585 1586 <xsd:element name="assignment_expression_q" type="Expression_Class"/> 1587 1588 where Expression_Class is defined by an xsd:choice of all the 1589 various kinds of expression. 1590 1591 The 'sloc' of each element indicates the starting and ending line and 1592 column numbers. Column numbers are character counts; that is, a tab 1593 counts as 1, not as however many spaces it might expand to. 1594 1595 Subelements of type Element have names ending in '_q' (for ASIS 1596 "Query"), and those of type Element_List end in '_ql' 1597 ("Query returning List"). 1598 1599 Some subelements are 'Boolean'. For example, Private_Type_Definition 1600 has has_abstract_q and has_limited_q, to indicate whether those 1601 keywords are present, as in `type T is abstract limited private;`. 1602 False is represented by a Nil_Element. True is represented 1603 by an element type specific to that query (for example, Abstract and 1604 Limited). 1605 1606 The root of the tree is a Compilation_Unit, with attributes: 1607 1608 * unit_kind, unit_class, and unit_origin. These are strings that match the 1609 enumeration literals of types Unit_Kinds, Unit_Classes, and Unit_Origins 1610 in package Asis. 1611 1612 * unit_full_name is the full expanded name of the unit, starting from a 1613 root library unit. So for `package P.Q.R is ...`, 1614 `unit_full_name="P.Q.R"`. Same for `separate (P.Q) package R is ...`. 1615 1616 * def_name is the same as unit_full_name for library units; for subunits, 1617 it is just the simple name. 1618 1619 * source_file is the name of the Ada source file. For example, for 1620 the spec of `P.Q.R`, `source_file="p-q-r.ads"`. This allows one to 1621 interpret the source locations --- the 'sloc' of all elements 1622 within this Compilation_Unit refers to line and column numbers 1623 within the named file. 1624 1625 Defining occurrences have these attributes: 1626 1627 * def_name is the simple name of the declared entity, as written in the Ada 1628 source code. 1629 1630 * def is a unique URI of the form: 1631 1632 :: 1633 1634 ada://kind/fully/qualified/name 1635 1636 where: 1637 1638 * kind indicates the kind of Ada entity being declared (see below), and 1639 1640 * fully/qualified/name, is the fully qualified name of the Ada 1641 entity, with each of 'fully', 'qualified', and 'name' being 1642 mangled for uniqueness. We do not document the mangling 1643 algorithm, which is subject to change; we just guarantee that the 1644 names are unique in the face of overloading. 1645 1646 * type is the type of the declared object, or `null` for 1647 declarations of things other than objects. 1648 1649 Usage occurrences have these attributes: 1650 1651 * ref_name is the same as the def_name of the corresponding defining 1652 occurrence. This attribute is not of much use, because of 1653 overloading; use ref for lookups, instead. 1654 1655 * ref is the same as the def of the corresponding defining 1656 occurrence. 1657 1658 In summary, `def_name` and `ref_name` are as in the source 1659 code of the declaration, possibly overloaded, whereas `def` and 1660 `ref` are unique-ified. 1661 1662 Literal elements have this attribute: 1663 1664 * lit_val is the value of the literal as written in the source text, 1665 appropriately escaped (e.g. `"` ---> `"`). This applies 1666 only to numeric and string literals. Enumeration literals in Ada are 1667 not really "literals" in the usual sense; they are usage occurrences, 1668 and have ref_name and ref as described above. Note also that string 1669 literals used as operator symbols are treated as defining or usage 1670 occurrences, not as literals. 1671 1672 Elements that can syntactically represent names and expressions (which 1673 includes usage occurrences, plus function calls and so forth) have this 1674 attribute: 1675 1676 * type. If the element represents an expression or the name of an object, 1677 'type' is the 'def' for the defining occurrence of the type of that 1678 expression or name. Names of other kinds of entities, such as package 1679 names and type names, do not have a type in Ada; these have type="null" 1680 in the XML. 1681 1682 Pragma elements have this attribute: 1683 1684 * pragma_name is the name of the pragma. For language-defined pragmas, the 1685 pragma name is redundant with the element kind (for example, an 1686 assert_pragma element necessarily has pragma_name="Assert"). However, all 1687 implementation-defined pragmas are lumped together in ASIS as a single 1688 element kind (for example, the GNAT-specific pragma Unreferenced is 1689 represented by an implementation_defined_pragma element with 1690 pragma_name="Unreferenced"). 1691 1692 Defining occurrences of formal parameters and generic formal objects have this 1693 attribute: 1694 1695 * mode indicates that the parameter is of mode 'in', 'in out', or 'out'. 1696 1697 All elements other than Not_An_Element have this attribute: 1698 1699 * checks is a comma-separated list of run-time checks that are needed 1700 for that element. The possible checks are: do_accessibility_check, 1701 do_discriminant_check,do_division_check,do_length_check, 1702 do_overflow_check,do_range_check,do_storage_check,do_tag_check. 1703 1704 The "kind" part of the "def" and "ref" attributes is taken from the ASIS 1705 enumeration type Flat_Declaration_Kinds, declared in 1706 Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_`` removed, and 1707 any trailing ``_Declaration`` or ``_Specification`` removed. Thus, the 1708 possible kinds are as follows: 1709 1710 :: 1711 1712 ordinary_type 1713 task_type 1714 protected_type 1715 incomplete_type 1716 tagged_incomplete_type 1717 private_type 1718 private_extension 1719 subtype 1720 variable 1721 constant 1722 deferred_constant 1723 single_task 1724 single_protected 1725 integer_number 1726 real_number 1727 enumeration_literal 1728 discriminant 1729 component 1730 loop_parameter 1731 generalized_iterator 1732 element_iterator 1733 procedure 1734 function 1735 parameter 1736 procedure_body 1737 function_body 1738 return_variable 1739 return_constant 1740 null_procedure 1741 expression_function 1742 package 1743 package_body 1744 object_renaming 1745 exception_renaming 1746 package_renaming 1747 procedure_renaming 1748 function_renaming 1749 generic_package_renaming 1750 generic_procedure_renaming 1751 generic_function_renaming 1752 task_body 1753 protected_body 1754 entry 1755 entry_body 1756 entry_index 1757 procedure_body_stub 1758 function_body_stub 1759 package_body_stub 1760 task_body_stub 1761 protected_body_stub 1762 exception 1763 choice_parameter 1764 generic_procedure 1765 generic_function 1766 generic_package 1767 package_instantiation 1768 procedure_instantiation 1769 function_instantiation 1770 formal_object 1771 formal_type 1772 formal_incomplete_type 1773 formal_procedure 1774 formal_function 1775 formal_package 1776 formal_package_declaration_with_box 1777 1778 .. _Generating_Representation_Clauses: 1779 1780 Generating Representation Clauses 1781 --------------------------------- 1782 1783 If the *--rep-clauses* switch is given, *gnat2xml* will 1784 generate representation clauses for certain types showing the 1785 representation chosen by the compiler. The information is produced by 1786 the ASIS 'Data Decomposition' facility --- see the 1787 `Asis.Data_Decomposition` package for details. 1788 1789 Not all types are supported. For example, `Type_Model_Kind` must 1790 be `A_Simple_Static_Model`. Types declared within generic units 1791 have no representation. The clauses that are generated include 1792 `attribute_definition_clauses` for `Size` and 1793 `Component_Size`, as well as 1794 `record_representation_clauses`. 1795 1796 There is no guarantee that the generated representation clauses could 1797 have actually come from legal Ada code; Ada has some restrictions that 1798 are not necessarily obeyed by the generated clauses. 1799 1800 The representation clauses are surrounded by comment elements to 1801 indicate that they are automatically generated, something like this: 1802 1803 :: 1804 1805 <comment text="--gen+"> 1806 ... 1807 <attribute_definition_clause> 1808 ... 1809 <comment text="--gen-"> 1810 ... 1811 1812 1813.. only:: PRO or GPL 1814 1815 .. _The_Program_Property_Verifier_gnatcheck: 1816 1817 The Program Property Verifier *gnatcheck* 1818 ========================================= 1819 1820 .. index:: ! gnatcheck 1821 .. index:: ASIS 1822 1823 The *gnatcheck* tool is an ASIS-based utility that checks properties 1824 of Ada source files according to a given set of semantic rules. 1825 1826 In order to check compliance with a given rule, *gnatcheck* has to 1827 semantically analyze the Ada sources. 1828 Therefore, checks can only be performed on 1829 legal Ada units. Moreover, when a unit depends semantically upon units located 1830 outside the current directory, the source search path has to be provided when 1831 calling *gnatcheck*, either through a specified project file or 1832 through *gnatcheck* switches. 1833 1834 For full details, refer to :title:`GNATcheck Reference Manual`. 1835 1836 1837 1838.. only:: PRO or GPL 1839 1840 .. _The_GNAT_Metrics_Tool_gnatmetric: 1841 1842 The GNAT Metrics Tool *gnatmetric* 1843 ================================== 1844 1845 .. index:: ! gnatmetric 1846 .. index:: Metric tool 1847 1848 The *gnatmetric* tool is an ASIS-based utility 1849 for computing various program metrics. 1850 It takes an Ada source file as input and generates a file containing the 1851 metrics data as output. Various switches control which 1852 metrics are computed and output. 1853 1854 To compute program metrics, *gnatmetric* invokes the Ada 1855 compiler and generates and uses the ASIS tree for the input source; 1856 thus the input must be legal Ada code, and the tool should have all the 1857 information needed to compile the input source. To provide this information, 1858 you may specify as a tool parameter the project file the input source belongs to 1859 (or you may call *gnatmetric* 1860 through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`). 1861 Another possibility is to specify the source search 1862 path and needed configuration files in *-cargs* section of *gnatmetric* 1863 call, see the description of the *gnatmetric* switches below. 1864 1865 If the set of sources to be processed by `gnatmetric` contains sources with 1866 preprocessing directives 1867 then the needed options should be provided to run preprocessor as a part of 1868 the *gnatmetric* call, and the computed metrics 1869 will correspond to preprocessed sources. 1870 1871 The *gnatmetric* command has the form 1872 1873 :: 1874 1875 $ gnatmetric [`switches`] {`filename`} [-cargs `gcc_switches`] 1876 1877 where: 1878 1879 * `switches` specify the metrics to compute and define the destination for 1880 the output 1881 1882 * Each `filename` is the name (including the extension) of a source 1883 file to process. 'Wildcards' are allowed, and 1884 the file name may contain path information. 1885 If no `filename` is supplied, then the `switches` list must contain 1886 at least one 1887 *-files* switch (see :ref:`Other_gnatmetric_Switches`). 1888 Including both a *-files* switch and one or more 1889 `filename` arguments is permitted. 1890 1891 * `gcc_switches` is a list of switches for 1892 *gcc*. They will be passed on to all compiler invocations made by 1893 *gnatmetric* to generate the ASIS trees. Here you can provide 1894 *-I* switches to form the source search path, 1895 and use the *-gnatec* switch to set the configuration file, 1896 use the *-gnat05* switch if sources should be compiled in 1897 Ada 2005 mode etc. 1898 1899 The following subsections describe the various switches accepted by 1900 *gnatmetric*, organized by category. 1901 1902 .. _Output_File_Control-gnatmetric: 1903 1904 Output File Control 1905 ------------------- 1906 1907 .. index:: Output file control in gnatmetric 1908 1909 *gnatmetric* has two output formats. It can generate a 1910 textual (human-readable) form, and also XML. By default only textual 1911 output is generated. 1912 1913 When generating the output in textual form, *gnatmetric* creates 1914 for each Ada source file a corresponding text file 1915 containing the computed metrics, except for the case when the set of metrics 1916 specified by gnatmetric parameters consists only of metrics that are computed 1917 for the whole set of analyzed sources, but not for each Ada source. 1918 By default, the name of the file containing metric information for a source 1919 is obtained by appending the :file:`.metrix` suffix to the 1920 name of the input source file. If not otherwise specified and no project file 1921 is specified as *gnatmetric* option this file is placed in the same 1922 directory as where the source file is located. If *gnatmetric* has a 1923 project file as its parameter, it places all the generated files in the 1924 object directory of the project (or in the project source directory if the 1925 project does not define an objects directory), if *--subdirs* option 1926 is specified, the files are placed in the subrirectory of this directory 1927 specified by this option. 1928 1929 All the output information generated in XML format is placed in a single 1930 file. By default the name of this file is :file:`metrix.xml`. 1931 If not otherwise specified and if no project file is specified 1932 as *gnatmetric* option this file is placed in the 1933 current directory. 1934 1935 Some of the computed metrics are summed over the units passed to 1936 *gnatmetric*; for example, the total number of lines of code. 1937 By default this information is sent to :file:`stdout`, but a file 1938 can be specified with the *-og* switch. 1939 1940 The following switches control the *gnatmetric* output: 1941 1942 .. index:: -x (gnatmetric) 1943 1944 :samp:`-x` 1945 Generate the XML output 1946 1947 .. index:: -xs (gnatmetric) 1948 1949 :samp:`-xs` 1950 Generate the XML output and the XML schema file that describes the structure 1951 of the XML metric report, this schema is assigned to the XML file. The schema 1952 file has the same name as the XML output file with :file:`.xml` suffix replaced 1953 with :file:`.xsd` 1954 1955 .. index:: -nt (gnatmetric) 1956 1957 1958 :samp:`-nt` 1959 Do not generate the output in text form (implies *-x*) 1960 1961 .. index:: -d (gnatmetric) 1962 1963 1964 :samp:`-d {output_dir}` 1965 Put text files with detailed metrics into `output_dir` 1966 1967 .. index:: -o (gnatmetric) 1968 1969 1970 :samp:`-o {file_suffix}` 1971 Use `file_suffix`, instead of :file:`.metrix` 1972 in the name of the output file. 1973 1974 .. index:: -og (gnatmetric) 1975 1976 1977 :samp:`-og {file_name}` 1978 Put global metrics into `file_name` 1979 1980 .. index:: -ox (gnatmetric) 1981 1982 1983 :samp:`-ox {file_name}` 1984 Put the XML output into `file_name` (also implies *-x*) 1985 1986 .. index:: -sfn (gnatmetric) 1987 1988 1989 :samp:`-sfn` 1990 Use 'short' source file names in the output. (The *gnatmetric* 1991 output includes the name(s) of the Ada source file(s) from which the metrics 1992 are computed. By default each name includes the absolute path. The 1993 *-sfn* switch causes *gnatmetric* 1994 to exclude all directory information from the file names that are output.) 1995 1996 1997 .. index:: Disable Metrics For Local Units in gnatmetric 1998 1999 .. _Disable_Metrics_For_Local_Units: 2000 2001 Disable Metrics For Local Units 2002 ------------------------------- 2003 2004 *gnatmetric* relies on the GNAT compilation model -- 2005 one compilation 2006 unit per one source file. It computes line metrics for the whole source 2007 file, and it also computes syntax 2008 and complexity metrics for the file's outermost unit. 2009 2010 By default, *gnatmetric* will also compute all metrics for certain 2011 kinds of locally declared program units: 2012 2013 * subprogram (and generic subprogram) bodies; 2014 2015 * package (and generic package) specs and bodies; 2016 2017 * task object and type specifications and bodies; 2018 2019 * protected object and type specifications and bodies. 2020 2021 .. index:: Eligible local unit (for gnatmetric) 2022 2023 These kinds of entities will be referred to as 2024 *eligible local program units*, or simply *eligible local units*, 2025 in the discussion below. 2026 2027 Note that a subprogram declaration, generic instantiation, 2028 or renaming declaration only receives metrics 2029 computation when it appear as the outermost entity 2030 in a source file. 2031 2032 Suppression of metrics computation for eligible local units can be 2033 obtained via the following switch: 2034 2035 2036 .. index:: -nolocal (gnatmetric) 2037 2038 2039 :samp:`-nolocal` 2040 Do not compute detailed metrics for eligible local program units 2041 2042 2043 .. _Specifying_a_set_of_metrics_to_compute: 2044 2045 Specifying a set of metrics to compute 2046 -------------------------------------- 2047 2048 By default all the metrics are computed and reported. The switches 2049 described in this subsection allow you to control, on an individual 2050 basis, whether metrics are computed and 2051 reported. If at least one positive metric 2052 switch is specified (that is, a switch that defines that a given 2053 metric or set of metrics is to be computed), then only 2054 explicitly specified metrics are reported. 2055 2056 .. _Line_Metrics_Control: 2057 2058 Line Metrics Control 2059 ^^^^^^^^^^^^^^^^^^^^ 2060 2061 .. index:: Line metrics control in gnatmetric 2062 2063 For any (legal) source file, and for each of its 2064 eligible local program units, *gnatmetric* computes the following 2065 metrics: 2066 2067 * the total number of lines; 2068 2069 * the total number of code lines (i.e., non-blank lines that are not comments) 2070 2071 * the number of comment lines 2072 2073 * the number of code lines containing end-of-line comments; 2074 2075 * the comment percentage: the ratio between the number of lines that contain 2076 comments and the number of all non-blank lines, expressed as a percentage; 2077 2078 * the number of empty lines and lines containing only space characters and/or 2079 format effectors (blank lines) 2080 2081 * the average number of code lines in subprogram bodies, task bodies, entry 2082 bodies and statement sequences in package bodies (this metric is only computed 2083 across the whole set of the analyzed units) 2084 2085 *gnatmetric* sums the values of the line metrics for all the 2086 files being processed and then generates the cumulative results. The tool 2087 also computes for all the files being processed the average number of code 2088 lines in bodies. 2089 2090 You can use the following switches to select the specific line metrics 2091 to be computed and reported. 2092 2093 2094 .. index:: --lines (gnatmetric) 2095 .. index:: --no-lines (gnatmetric) 2096 2097 2098 :samp:`-lines-all` 2099 Report all the line metrics 2100 2101 2102 :samp:`-no-lines-all` 2103 Do not report any of line metrics 2104 2105 2106 :samp:`-lines` 2107 Report the number of all lines 2108 2109 2110 :samp:`-no-lines` 2111 Do not report the number of all lines 2112 2113 2114 :samp:`-lines-code` 2115 Report the number of code lines 2116 2117 2118 :samp:`-no-lines-code` 2119 Do not report the number of code lines 2120 2121 2122 :samp:`-lines-comment` 2123 Report the number of comment lines 2124 2125 2126 :samp:`-no-lines-comment` 2127 Do not report the number of comment lines 2128 2129 2130 :samp:`-lines-eol-comment` 2131 Report the number of code lines containing 2132 end-of-line comments 2133 2134 2135 :samp:`-no-lines-eol-comment` 2136 Do not report the number of code lines containing 2137 end-of-line comments 2138 2139 2140 :samp:`-lines-ratio` 2141 Report the comment percentage in the program text 2142 2143 2144 :samp:`-no-lines-ratio` 2145 Do not report the comment percentage in the program text 2146 2147 2148 :samp:`-lines-blank` 2149 Report the number of blank lines 2150 2151 2152 :samp:`-no-lines-blank` 2153 Do not report the number of blank lines 2154 2155 2156 :samp:`-lines-average` 2157 Report the average number of code lines in subprogram bodies, task bodies, 2158 entry bodies and statement sequences in package bodies. The metric is computed 2159 and reported for the whole set of processed Ada sources only. 2160 2161 2162 :samp:`-no-lines-average` 2163 Do not report the average number of code lines in subprogram bodies, 2164 task bodies, entry bodies and statement sequences in package bodies. 2165 2166 2167 .. _Syntax_Metrics_Control: 2168 2169 Syntax Metrics Control 2170 ^^^^^^^^^^^^^^^^^^^^^^ 2171 2172 .. index:: Syntax metrics control in gnatmetric 2173 2174 *gnatmetric* computes various syntactic metrics for the 2175 outermost unit and for each eligible local unit: 2176 2177 * *LSLOC ('Logical Source Lines Of Code')* 2178 The total number of declarations and the total number of statements. Note 2179 that the definition of declarations is the one given in the reference 2180 manual: 2181 2182 "Each of the following is defined to be a declaration: any basic_declaration; 2183 an enumeration_literal_specification; a discriminant_specification; 2184 a component_declaration; a loop_parameter_specification; a 2185 parameter_specification; a subprogram_body; an entry_declaration; 2186 an entry_index_specification; a choice_parameter_specification; 2187 a generic_formal_parameter_declaration." 2188 2189 This means for example that each enumeration literal adds one to the count, 2190 as well as each subprogram parameter. 2191 2192 Thus the results from this metric will be significantly greater than might 2193 be expected from a naive view of counting semicolons. 2194 2195 * *Maximal static nesting level of inner program units* 2196 According to :title:`Ada Reference Manual`, 10.1(1): 2197 2198 "A program unit is either a package, a task unit, a protected unit, a 2199 protected entry, a generic unit, or an explicitly declared subprogram other 2200 than an enumeration literal." 2201 2202 * *Maximal nesting level of composite syntactic constructs* 2203 This corresponds to the notion of the 2204 maximum nesting level in the GNAT built-in style checks 2205 (see :ref:`Style_Checking`) 2206 2207 For the outermost unit in the file, *gnatmetric* additionally computes 2208 the following metrics: 2209 2210 * *Public subprograms* 2211 This metric is computed for package specs. It is the 2212 number of subprograms and generic subprograms declared in the visible 2213 part (including the visible part of nested packages, protected objects, and 2214 protected types). 2215 2216 2217 * *All subprograms* 2218 This metric is computed for bodies and subunits. The 2219 metric is equal to a total number of subprogram bodies in the compilation 2220 unit. 2221 Neither generic instantiations nor renamings-as-a-body nor body stubs 2222 are counted. Any subprogram body is counted, independently of its nesting 2223 level and enclosing constructs. Generic bodies and bodies of protected 2224 subprograms are counted in the same way as 'usual' subprogram bodies. 2225 2226 2227 * *Public types* 2228 This metric is computed for package specs and 2229 generic package declarations. It is the total number of types 2230 that can be referenced from outside this compilation unit, plus the 2231 number of types from all the visible parts of all the visible generic 2232 packages. Generic formal types are not counted. Only types, not subtypes, 2233 are included. 2234 2235 Along with the total number of public types, the following 2236 types are counted and reported separately: 2237 2238 * *Abstract types* 2239 2240 * *Root tagged types^ (abstract, non-abstract, private, non-private). Type 2241 extensions are *not* counted 2242 2243 * *Private types* (including private extensions) 2244 2245 * *Task types* 2246 2247 * *Protected types* 2248 2249 * *All types* 2250 This metric is computed for any compilation unit. It is equal to the total 2251 number of the declarations of different types given in the compilation unit. 2252 The private and the corresponding full type declaration are counted as one 2253 type declaration. Incomplete type declarations and generic formal types 2254 are not counted. 2255 No distinction is made among different kinds of types (abstract, 2256 private etc.); the total number of types is computed and reported. 2257 2258 By default, all the syntax metrics are computed and reported. You can use the 2259 following switches to select specific syntax metrics. 2260 2261 2262 .. index:: --syntax (gnatmetric) 2263 .. index:: --no-syntax (gnatmetric) 2264 2265 2266 :samp:`-syntax-all` 2267 Report all the syntax metrics 2268 2269 2270 :samp:`-no-syntax-all` 2271 Do not report any of syntax metrics 2272 2273 2274 :samp:`-declarations` 2275 Report the total number of declarations 2276 2277 2278 :samp:`-no-declarations` 2279 Do not report the total number of declarations 2280 2281 2282 :samp:`-statements` 2283 Report the total number of statements 2284 2285 2286 :samp:`-no-statements` 2287 Do not report the total number of statements 2288 2289 2290 :samp:`-public-subprograms` 2291 Report the number of public subprograms in a compilation unit 2292 2293 2294 :samp:`-no-public-subprograms` 2295 Do not report the number of public subprograms in a compilation unit 2296 2297 2298 :samp:`-all-subprograms` 2299 Report the number of all the subprograms in a compilation unit 2300 2301 2302 :samp:`-no-all-subprograms` 2303 Do not report the number of all the subprograms in a compilation unit 2304 2305 2306 :samp:`-public-types` 2307 Report the number of public types in a compilation unit 2308 2309 2310 :samp:`-no-public-types` 2311 Do not report the number of public types in a compilation unit 2312 2313 2314 :samp:`-all-types` 2315 Report the number of all the types in a compilation unit 2316 2317 2318 :samp:`-no-all-types` 2319 Do not report the number of all the types in a compilation unit 2320 2321 2322 :samp:`-unit-nesting` 2323 Report the maximal program unit nesting level 2324 2325 2326 :samp:`-no-unit-nesting` 2327 Do not report the maximal program unit nesting level 2328 2329 2330 :samp:`-construct-nesting` 2331 Report the maximal construct nesting level 2332 2333 2334 :samp:`-no-construct-nesting` 2335 Do not report the maximal construct nesting level 2336 2337 2338 .. _Complexity_Metrics_Control: 2339 2340 Complexity Metrics Control 2341 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 2342 2343 .. index:: Complexity metrics control in gnatmetric 2344 2345 For a program unit that is an executable body (a subprogram body (including 2346 generic bodies), task body, entry body or a package body containing 2347 its own statement sequence) *gnatmetric* computes the following 2348 complexity metrics: 2349 2350 * McCabe cyclomatic complexity; 2351 2352 * McCabe essential complexity; 2353 2354 * maximal loop nesting level; 2355 2356 * extra exit points (for subprograms); 2357 2358 The McCabe cyclomatic complexity metric is defined 2359 in `http://www.mccabe.com/pdf/mccabe-nist235r.pdf <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_ 2360 2361 According to McCabe, both control statements and short-circuit control forms 2362 should be taken into account when computing cyclomatic complexity. 2363 For Ada 2012 we have also take into account conditional expressions 2364 and quantified expressions. For each body, we compute three metric values: 2365 2366 * the complexity introduced by control 2367 statements only, without taking into account short-circuit forms 2368 (referred as `statement complexity` in *gnatmetric* output), 2369 2370 * the complexity introduced by short-circuit control forms only 2371 (referred as `expression complexity` in *gnatmetric* output), and 2372 2373 * the total 2374 cyclomatic complexity, which is the sum of these two values 2375 (referred as `cyclomatic complexity` in *gnatmetric* output). 2376 2377 The cyclomatic complexity is also computed for Ada 2012 expression functions. 2378 An expression function cannot have statements as its components, so only one 2379 metric value is computed as a cyclomatic complexity of an expression function. 2380 2381 The origin of cyclomatic complexity metric is the need to estimate the number 2382 of independent paths in the control flow graph that in turn gives the number 2383 of tests needed to satisfy paths coverage testing completeness criterion. 2384 Considered from the testing point of view, a static Ada `loop` (that is, 2385 the `loop` statement having static subtype in loop parameter 2386 specification) does not add to cyclomatic complexity. By providing 2387 *--no-static-loop* option a user 2388 may specify that such loops should not be counted when computing the 2389 cyclomatic complexity metric 2390 2391 The Ada essential complexity metric is a McCabe cyclomatic complexity metric 2392 counted for the code that is reduced by excluding all the pure structural Ada 2393 control statements. An compound statement is considered as a non-structural 2394 if it contains a `raise` or `return` statement as it subcomponent, 2395 or if it contains a `goto` statement that transfers the control outside 2396 the operator. A selective accept statement with `terminate` alternative 2397 is considered as non-structural statement. When computing this metric, 2398 `exit` statements are treated in the same way as `goto` 2399 statements unless *-ne* option is specified. 2400 2401 The Ada essential complexity metric defined here is intended to quantify 2402 the extent to which the software is unstructured. It is adapted from 2403 the McCabe essential complexity metric defined in 2404 http://www.mccabe.com/pdf/mccabe-nist235r.pdf 2405 but is modified to be more 2406 suitable for typical Ada usage. For example, short circuit forms 2407 are not penalized as unstructured in the Ada essential complexity metric. 2408 2409 When computing cyclomatic and essential complexity, *gnatmetric* skips 2410 the code in the exception handlers and in all the nested program units. The 2411 code of assertions and predicates (that is, subprogram preconditions and 2412 postconditions, subtype predicates and type invariants) is also skipped. 2413 2414 By default, all the complexity metrics are computed and reported. 2415 For more fine-grained control you can use 2416 the following switches: 2417 2418 2419 .. index:: -complexity (gnatmetric) 2420 .. index:: --no-complexity (gnatmetric) 2421 2422 2423 :samp:`-complexity-all` 2424 Report all the complexity metrics 2425 2426 2427 :samp:`-no-complexity-all` 2428 Do not report any of complexity metrics 2429 2430 2431 :samp:`-complexity-cyclomatic` 2432 Report the McCabe Cyclomatic Complexity 2433 2434 2435 :samp:`-no-complexity-cyclomatic` 2436 Do not report the McCabe Cyclomatic Complexity 2437 2438 2439 :samp:`-complexity-essential` 2440 Report the Essential Complexity 2441 2442 2443 :samp:`-no-complexity-essential` 2444 Do not report the Essential Complexity 2445 2446 2447 :samp:`-loop-nesting` 2448 Report maximal loop nesting level 2449 2450 2451 :samp:`-no-loop-nesting` 2452 Do not report maximal loop nesting level 2453 2454 2455 :samp:`-complexity-average` 2456 Report the average McCabe Cyclomatic Complexity for all the subprogram bodies, 2457 task bodies, entry bodies and statement sequences in package bodies. 2458 The metric is computed and reported for whole set of processed Ada sources 2459 only. 2460 2461 2462 :samp:`-no-complexity-average` 2463 Do not report the average McCabe Cyclomatic Complexity for all the subprogram 2464 bodies, task bodies, entry bodies and statement sequences in package bodies 2465 2466 .. index:: -ne (gnatmetric) 2467 2468 2469 :samp:`-ne` 2470 Do not consider `exit` statements as `goto`\ s when 2471 computing Essential Complexity 2472 2473 .. index:: --no-static-loop (gnatmetric) 2474 2475 2476 :samp:`-no-static-loop` 2477 Do not consider static loops when computing cyclomatic complexity 2478 2479 2480 :samp:`-extra-exit-points` 2481 Report the extra exit points for subprogram bodies. As an exit point, this 2482 metric counts `return` statements and raise statements in case when the 2483 raised exception is not handled in the same body. In case of a function this 2484 metric subtracts 1 from the number of exit points, because a function body 2485 must contain at least one `return` statement. 2486 2487 2488 :samp:`-no-extra-exit-points` 2489 Do not report the extra exit points for subprogram bodies 2490 2491 2492 .. _Coupling_Metrics_Control: 2493 2494 Coupling Metrics Control 2495 ^^^^^^^^^^^^^^^^^^^^^^^^ 2496 2497 .. index:: Coupling metrics control in gnatmetric 2498 2499 .. index:: Coupling metrics (in gnatmetric) 2500 2501 Coupling metrics measure the dependencies between a given entity and other 2502 entities in the program. This information is useful since high coupling 2503 may signal potential issues with maintainability as the program evolves. 2504 2505 *gnatmetric* computes the following coupling metrics: 2506 2507 2508 * *object-oriented coupling*, for classes in traditional object-oriented 2509 sense; 2510 2511 * *unit coupling*, for all the program units making up a program; 2512 2513 * *control coupling*, reflecting dependencies between a unit and 2514 other units that contain subprograms. 2515 2516 .. index:: fan-out coupling 2517 .. index:: efferent coupling 2518 2519 Two kinds of coupling metrics are computed: 2520 2521 * fan-out coupling ('efferent coupling'): 2522 the number of entities the given entity depends upon. This metric 2523 reflects how the given entity depends on the changes in the 2524 'external world'. 2525 2526 .. index:: fan-in coupling 2527 .. index:: afferent coupling 2528 2529 * fan-in coupling ('afferent' coupling): 2530 the number of entities that depend on a given entity. 2531 This metric reflects how the 'external world' depends on the changes in a 2532 given entity. 2533 2534 Object-oriented coupling metrics measure the dependencies 2535 between a given class (or a group of classes) and the other classes in the 2536 program. In this subsection the term 'class' is used in its traditional 2537 object-oriented programming sense (an instantiable module that contains data 2538 and/or method members). A *category* (of classes) is a group of closely 2539 related classes that are reused and/or modified together. 2540 2541 A class `K`'s fan-out coupling is the number of classes 2542 that `K` depends upon. 2543 A category's fan-out coupling is the number of classes outside the 2544 category that the classes inside the category depend upon. 2545 2546 A class `K`'s fan-in coupling is the number of classes 2547 that depend upon `K`. 2548 A category's fan-in coupling is the number of classes outside the 2549 category that depend on classes belonging to the category. 2550 2551 Ada's object-oriented paradigm separates the instantiable entity 2552 (type) from the module (package), so the definition of the coupling 2553 metrics for Ada maps the class and class category notions 2554 onto Ada constructs. 2555 2556 For the coupling metrics, several kinds of modules that define a tagged type 2557 or an interface type -- library packages, library generic packages, and 2558 library generic package instantiations -- are considered to be classes. 2559 A category consists of a library package (or 2560 a library generic package) that defines a tagged or an interface type, 2561 together with all its descendant (generic) packages that define tagged 2562 or interface types. Thus a 2563 category is an Ada hierarchy of library-level program units. Class 2564 coupling in Ada is referred to as 'tagged coupling', and category coupling 2565 is referred to as 'hierarchy coupling'. 2566 2567 For any package serving as a class, its body and subunits (if any) are 2568 considered together with its spec when computing dependencies, and coupling 2569 metrics are reported for spec units only. Dependencies between classes 2570 mean Ada semantic dependencies. For object-oriented coupling 2571 metrics, only dependencies on units treated as classes are 2572 considered. 2573 2574 Similarly, for unit and control coupling an entity is considered to be the 2575 conceptual construct consisting of the entity's specification, body, and 2576 any subunits (transitively). 2577 *gnatmetric* computes 2578 the dependencies of all these units as a whole, but 2579 metrics are only reported for spec 2580 units (or for a subprogram body unit in case if there is no 2581 separate spec for the given subprogram). 2582 2583 For unit coupling, dependencies are computed between all kinds of program 2584 units. For control coupling, the dependencies of a given unit are limited to 2585 those units that define subprograms. Thus control fan-out coupling is reported 2586 for all units, but control fan-in coupling is only reported for units 2587 that define subprograms. 2588 2589 The following simple example illustrates the difference between unit coupling 2590 and control coupling metrics: 2591 2592 .. code-block:: ada 2593 2594 package Lib_1 is 2595 function F_1 (I : Integer) return Integer; 2596 end Lib_1; 2597 2598 package Lib_2 is 2599 type T_2 is new Integer; 2600 end Lib_2; 2601 2602 package body Lib_1 is 2603 function F_1 (I : Integer) return Integer is 2604 begin 2605 return I + 1; 2606 end F_1; 2607 end Lib_1; 2608 2609 with Lib_2; use Lib_2; 2610 package Pack is 2611 Var : T_2; 2612 function Fun (I : Integer) return Integer; 2613 end Pack; 2614 2615 with Lib_1; use Lib_1; 2616 package body Pack is 2617 function Fun (I : Integer) return Integer is 2618 begin 2619 return F_1 (I); 2620 end Fun; 2621 end Pack; 2622 2623 If we apply *gnatmetric* with the *--coupling-all* option to 2624 these units, the result will be: 2625 2626 :: 2627 2628 Coupling metrics: 2629 ================= 2630 Unit Lib_1 (C:\\customers\\662\\L406-007\\lib_1.ads) 2631 control fan-out coupling : 0 2632 control fan-in coupling : 1 2633 unit fan-out coupling : 0 2634 unit fan-in coupling : 1 2635 2636 Unit Pack (C:\\customers\\662\\L406-007\\pack.ads) 2637 control fan-out coupling : 1 2638 control fan-in coupling : 0 2639 unit fan-out coupling : 2 2640 unit fan-in coupling : 0 2641 2642 Unit Lib_2 (C:\\customers\\662\\L406-007\\lib_2.ads) 2643 control fan-out coupling : 0 2644 unit fan-out coupling : 0 2645 unit fan-in coupling : 1 2646 2647 The result does not contain values for object-oriented 2648 coupling because none of the argument units contains a tagged type and 2649 therefore none of these units can be treated as a class. 2650 2651 The `Pack` package (spec and body) depends on two 2652 units -- `Lib_1` `and Lib_2` -- and so its unit fan-out coupling 2653 is 2. Since nothing depends on it, its unit fan-in coupling is 0, as 2654 is its control fan-in coupling. Only one of the units `Pack` depends 2655 upon defines a subprogram, so its control fan-out coupling is 1. 2656 2657 `Lib_2` depends on nothing, so its fan-out metrics are 0. It does 2658 not define any subprograms, so it has no control fan-in metric. 2659 One unit (`Pack`) depends on it , so its unit fan-in coupling is 1. 2660 2661 `Lib_1` is similar to `Lib_2`, but it does define a subprogram. 2662 Its control fan-in coupling is 1 (because there is one unit 2663 depending on it). 2664 2665 When computing coupling metrics, *gnatmetric* counts only 2666 dependencies between units that are arguments of the *gnatmetric* 2667 invocation. Coupling metrics are program-wide (or project-wide) metrics, so 2668 you should invoke *gnatmetric* for 2669 the complete set of sources comprising your program. This can be done 2670 by invoking *gnatmetric* with the corresponding project file 2671 and with the *-U* option. 2672 2673 By default, all the coupling metrics are disabled. You can use the following 2674 switches to specify the coupling metrics to be computed and reported: 2675 2676 .. index:: --tagged-coupling (gnatmetric) 2677 .. index:: --hierarchy-coupling (gnatmetric) 2678 .. index:: --unit-coupling (gnatmetric) 2679 .. index:: --control-coupling (gnatmetric) 2680 2681 :samp:`-coupling-all` 2682 Report all the coupling metrics 2683 2684 2685 :samp:`-tagged-coupling-out` 2686 Report tagged (class) fan-out coupling 2687 2688 2689 :samp:`-tagged-coupling-in` 2690 Report tagged (class) fan-in coupling 2691 2692 2693 :samp:`-hierarchy-coupling-out` 2694 Report hierarchy (category) fan-out coupling 2695 2696 2697 :samp:`-hierarchy-coupling-in` 2698 Report hierarchy (category) fan-in coupling 2699 2700 2701 :samp:`-unit-coupling-out` 2702 Report unit fan-out coupling 2703 2704 2705 :samp:`-unit-coupling-in` 2706 Report unit fan-in coupling 2707 2708 2709 :samp:`-control-coupling-out` 2710 Report control fan-out coupling 2711 2712 2713 :samp:`-control-coupling-in` 2714 Report control fan-in coupling 2715 2716 2717 .. _Other_gnatmetric_Switches: 2718 2719 Other `gnatmetric` Switches 2720 --------------------------- 2721 2722 Additional *gnatmetric* switches are as follows: 2723 2724 2725 .. index:: --version (gnatmetric) 2726 2727 :samp:`-version` 2728 Display Copyright and version, then exit disregarding all other options. 2729 2730 2731 .. index:: --help (gnatmetric) 2732 2733 :samp:`-help` 2734 Display usage, then exit disregarding all other options. 2735 2736 2737 .. index:: -P (gnatmetric) 2738 2739 :samp:`-P {file}` 2740 Indicates the name of the project file that describes the set of sources 2741 to be processed. The exact set of argument sources depends on other options 2742 specified, see below. 2743 2744 2745 .. index:: -U (gnatmetric) 2746 2747 :samp:`-U` 2748 If a project file is specified and no argument source is explicitly 2749 specified (either directly or by means of *-files* option), process 2750 all the units of the closure of the argument project. Otherwise this option 2751 has no effect. 2752 2753 2754 :samp:`-U {main_unit}` 2755 If a project file is specified and no argument source is explicitly 2756 specified (either directly or by means of *-files* option), process 2757 the closure of units rooted at `main_unit`. Otherwise this option 2758 has no effect. 2759 2760 2761 .. index:: -X (gnatmetric) 2762 2763 :samp:`-X{name}={value}` 2764 Indicates that external variable `name` in the argument project 2765 has the value `value`. Has no effect if no project is specified as 2766 tool argument. 2767 2768 2769 .. index:: --RTS (gnatmetric) 2770 2771 :samp:`-RTS={rts-path}` 2772 Specifies the default location of the runtime library. Same meaning as the 2773 equivalent *gnatmake* flag (see :ref:`Switches_for_gnatmake`). 2774 2775 2776 .. index:: --subdirs=dir (gnatmetric) 2777 2778 :samp:`-subdirs={dir}` 2779 Use the specified subdirectory of the project objects file (or of the 2780 project file directory if the project does not specify an object directory) 2781 for tool output files. Has no effect if no project is specified as 2782 tool argument r if *--no_objects_dir* is specified. 2783 2784 2785 .. index:: --no_objects_dir (gnatmetric) 2786 2787 :samp:`-no_objects_dir` 2788 Place all the result files into the current directory instead of 2789 project objects directory. This corresponds to the *gnatcheck* 2790 behavior when it is called with the project file from the 2791 GNAT driver. Has no effect if no project is specified. 2792 2793 2794 .. index:: -files (gnatmetric) 2795 2796 :samp:`-files {filename}` 2797 Take the argument source files from the specified file. This file should be an 2798 ordinary text file containing file names separated by spaces or 2799 line breaks. You can use this switch more than once in the same call to 2800 *gnatmetric*. You also can combine this switch with 2801 an explicit list of files. 2802 2803 2804 .. index:: -j (gnatmetric) 2805 2806 :samp:`-j{n}` 2807 Use `n` processes to carry out the tree creations (internal representations 2808 of the argument sources). On a multiprocessor machine this speeds up processing 2809 of big sets of argument sources. If `n` is 0, then the maximum number of 2810 parallel tree creations is the number of core processors on the platform. 2811 2812 .. index:: -t (gnatmetric) 2813 2814 2815 :samp:`-t` 2816 Print out execution time. 2817 2818 2819 .. index:: -v (gnatmetric) 2820 2821 :samp:`-v` 2822 Verbose mode; 2823 *gnatmetric* generates version information and then 2824 a trace of sources being processed. 2825 2826 2827 .. index:: -q (gnatmetric) 2828 2829 :samp:`-q` 2830 Quiet mode. 2831 2832 If a project file is specified and no argument source is explicitly 2833 specified (either directly or by means of *-files* option), and no 2834 *-U* is specified, then the set of processed sources is 2835 all the immediate units of the argument project. 2836 2837 2838.. only:: PRO or GPL 2839 2840 .. _The_GNAT_Pretty-Printer_gnatpp: 2841 2842 The GNAT Pretty-Printer *gnatpp* 2843 ================================ 2844 2845 .. index:: ! gnatpp 2846 .. index:: Pretty-Printer 2847 2848 The *gnatpp* tool is an ASIS-based utility 2849 for source reformatting / pretty-printing. 2850 It takes an Ada source file as input and generates a reformatted 2851 version as output. 2852 You can specify various style directives via switches; e.g., 2853 identifier case conventions, rules of indentation, and comment layout. 2854 2855 To produce a reformatted file, *gnatpp* invokes the Ada 2856 compiler and generates and uses the ASIS tree for the input source; 2857 thus the input must be legal Ada code, and the tool should have all the 2858 information needed to compile the input source. To provide this information, 2859 you may specify as a tool parameter the project file the input source belongs to 2860 (or you may call *gnatpp* 2861 through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`). 2862 Another possibility is to specify the source search 2863 path and needed configuration files in ``-cargs`` section of *gnatpp* 2864 call, see the description of the *gnatpp* switches below. 2865 2866 *gnatpp* cannot process sources that contain preprocessing directives. 2867 2868 The *gnatpp* command has the form 2869 2870 :: 2871 2872 $ gnatpp [`switches`] `filename` [-cargs `gcc_switches`] 2873 2874 where 2875 2876 * `switches` is an optional sequence of switches defining such properties as 2877 the formatting rules, the source search path, and the destination for the 2878 output source file 2879 2880 * `filename` is the name (including the extension) of the source file to 2881 reformat; wildcards or several file names on the same gnatpp command are 2882 allowed. The file name may contain path information; it does not have to 2883 follow the GNAT file naming rules 2884 2885 * `gcc_switches` is a list of switches for 2886 *gcc*. They will be passed on to all compiler invocations made by 2887 *gnatpp* to generate the ASIS trees. Here you can provide 2888 ``-I`` switches to form the source search path, 2889 use the ``-gnatec`` switch to set the configuration file, etc. 2890 2891 2892 .. _Switches_for_gnatpp: 2893 2894 Switches for *gnatpp* 2895 --------------------- 2896 2897 The following subsections describe the various switches accepted by 2898 *gnatpp*, organized by category. 2899 2900 You specify a switch by supplying a name and generally also a value. 2901 In many cases the values for a switch with a given name are incompatible with 2902 each other 2903 (for example the switch that controls the casing of a reserved word may have 2904 exactly one value: upper case, lower case, or 2905 mixed case) and thus exactly one such switch can be in effect for an 2906 invocation of *gnatpp*. 2907 If more than one is supplied, the last one is used. 2908 However, some values for the same switch are mutually compatible. 2909 You may supply several such switches to *gnatpp*, but then 2910 each must be specified in full, with both the name and the value. 2911 Abbreviated forms (the name appearing once, followed by each value) are 2912 not permitted. 2913 2914 .. _Alignment_Control: 2915 2916 Alignment Control 2917 ^^^^^^^^^^^^^^^^^ 2918 2919 .. index:: Alignment control in gnatpp 2920 2921 Programs can be easier to read if certain constructs are vertically aligned. 2922 By default, alignment of the following constructs is set ON: 2923 2924 * ``:`` in declarations, 2925 * ``:=`` in initializations in declarations, 2926 * ``:=`` in assignment statements, 2927 * ``=>`` in associations, and 2928 * ``at`` keywords in the component clauses in record representation clauses. 2929 2930 2931 .. index:: -A0 (gnatpp) 2932 .. index:: -A1 (gnatpp) 2933 2934 2935 :samp:`-A0` 2936 Set alignment to OFF 2937 2938 2939 :samp:`-A1` 2940 Set alignment to ON 2941 2942 .. _Casing_Control: 2943 2944 2945 Casing Control 2946 ^^^^^^^^^^^^^^ 2947 2948 .. index:: Casing control in gnatpp 2949 2950 *gnatpp* allows you to specify the casing for reserved words, 2951 pragma names, attribute designators and identifiers. 2952 For identifiers you may define a 2953 general rule for name casing but also override this rule 2954 via a set of dictionary files. 2955 2956 Three types of casing are supported: lower case, upper case, and mixed case. 2957 'Mixed case' means that the first letter, and also each letter immediately 2958 following an underscore, are converted to their uppercase forms; 2959 all the other letters are converted to their lowercase forms. 2960 2961 .. index:: -a (gnatpp) 2962 2963 2964 :samp:`-aL` 2965 Attribute designators are lower case 2966 2967 2968 :samp:`-aU` 2969 Attribute designators are upper case 2970 2971 2972 :samp:`-aM` 2973 Attribute designators are mixed case (this is the default) 2974 2975 .. index:: -k (gnatpp) 2976 2977 2978 :samp:`-kL` 2979 Keywords (technically, these are known in Ada as *reserved words*) are 2980 lower case (this is the default) 2981 2982 2983 :samp:`-kU` 2984 Keywords are upper case 2985 2986 .. index:: -n (gnatpp) 2987 2988 2989 :samp:`-nD` 2990 Name casing for defining occurrences are as they appear in the source file 2991 (this is the default) 2992 2993 2994 :samp:`-nU` 2995 Names are in upper case 2996 2997 2998 :samp:`-nL` 2999 Names are in lower case 3000 3001 3002 :samp:`-nM` 3003 Names are in mixed case 3004 3005 .. index:: -ne (gnatpp) 3006 3007 3008 :samp:`-neD` 3009 Enumeration literal casing for defining occurrences are as they appear in the 3010 source file. Overrides -n casing setting. 3011 3012 3013 :samp:`-neU` 3014 Enumeration literals are in upper case. Overrides -n casing 3015 setting. 3016 3017 3018 :samp:`-neL` 3019 Enumeration literals are in lower case. Overrides -n casing 3020 setting. 3021 3022 3023 :samp:`-neM` 3024 Enumeration literals are in mixed case. Overrides -n casing 3025 setting. 3026 3027 .. index:: -nt (gnatpp) 3028 3029 3030 :samp:`-neD` 3031 Names introduced by type and subtype declarations are always 3032 cased as they appear in the declaration in the source file. 3033 Overrides -n casing setting. 3034 3035 3036 :samp:`-ntU` 3037 Names introduced by type and subtype declarations are always in 3038 upper case. Overrides -n casing setting. 3039 3040 3041 :samp:`-ntL` 3042 Names introduced by type and subtype declarations are always in 3043 lower case. Overrides -n casing setting. 3044 3045 3046 :samp:`-ntM` 3047 Names introduced by type and subtype declarations are always in 3048 mixed case. Overrides -n casing setting. 3049 3050 3051 :samp:`-nnU` 3052 Names introduced by number declarations are always in 3053 upper case. Overrides -n casing setting. 3054 3055 3056 :samp:`-nnL` 3057 Names introduced by number declarations are always in 3058 lower case. Overrides -n casing setting. 3059 3060 3061 :samp:`-nnM` 3062 Names introduced by number declarations are always in 3063 mixed case. Overrides -n casing setting. 3064 3065 .. index:: -p (gnatpp) 3066 3067 3068 :samp:`-pL` 3069 Pragma names are lower case 3070 3071 3072 :samp:`-pU` 3073 Pragma names are upper case 3074 3075 3076 :samp:`-pM` 3077 Pragma names are mixed case (this is the default) 3078 3079 3080 .. index:: -D (gnatpp) 3081 3082 :samp:`-D{file}` 3083 Use `file` as a *dictionary file* that defines 3084 the casing for a set of specified names, 3085 thereby overriding the effect on these names by 3086 any explicit or implicit 3087 -n switch. 3088 To supply more than one dictionary file, 3089 use several ``-D`` switches. 3090 3091 *gnatpp* implicitly uses a *default dictionary file* 3092 to define the casing for the Ada predefined names and 3093 the names declared in the GNAT libraries. 3094 3095 3096 .. index:: -D- (gnatpp) 3097 3098 :samp:`-D-` 3099 Do not use the default dictionary file; 3100 instead, use the casing 3101 defined by a ``-n`` switch and any explicit 3102 dictionary file(s) 3103 3104 The structure of a dictionary file, and details on the conventions 3105 used in the default dictionary file, are defined in :ref:`Name_Casing`. 3106 3107 The ``-D-`` and 3108 ``-D-``\ `file` switches are mutually 3109 compatible. 3110 3111 This group of *gnatpp* switches controls the layout of comments and 3112 complex syntactic constructs. See :ref:`Formatting_Comments` for details 3113 on their effect. 3114 3115 3116 .. index:: -c (gnatpp) 3117 3118 3119 :samp:`-c0` 3120 All comments remain unchanged. 3121 3122 3123 :samp:`-c1` 3124 GNAT-style comment line indentation. 3125 This is the default. 3126 3127 3128 :samp:`-c3` 3129 GNAT-style comment beginning. 3130 3131 3132 :samp:`-c4` 3133 Fill comment blocks. 3134 3135 3136 :samp:`-c5` 3137 Keep unchanged special form comments. 3138 This is the default. 3139 3140 3141 .. index:: --comments-only (gnatpp) 3142 3143 :samp:`--comments-only` 3144 Format just the comments. 3145 3146 .. index:: --no-separate-is (gnatpp) 3147 3148 3149 :samp:`--no-separate-is` 3150 Do not place the keyword `is` on a separate line in a subprogram body in 3151 case if the spec occupies more than one line. 3152 3153 .. index:: --separate-loop-then (gnatpp) 3154 3155 3156 :samp:`--separate-loop-then` 3157 Place the keyword `loop` in FOR and WHILE loop statements and the 3158 keyword `then` in IF statements on a separate line. 3159 3160 .. index:: --no-separate-loop-then (gnatpp) 3161 3162 3163 :samp:`--no-separate-loop-then` 3164 Do not place the keyword `loop` in FOR and WHILE loop statements and the 3165 keyword `then` in IF statements on a separate line. This option is 3166 incompatible with ``--separate-loop-then`` option. 3167 3168 .. index:: --use-on-new-line (gnatpp) 3169 3170 3171 :samp:`--use-on-new-line` 3172 Start each USE clause in a context clause from a separate line. 3173 3174 .. index:: --insert-blank-lines (gnatpp) 3175 3176 3177 :samp:`--insert-blank-lines` 3178 Insert blank lines where appropriate (between bodies and other large 3179 constructs). 3180 3181 .. index:: --preserve-blank-lines (gnatpp) 3182 3183 3184 :samp:`--preserve-blank-lines` 3185 Preserve blank lines in the input. By default, gnatpp will squeeze 3186 multiple blank lines down to one. 3187 3188 3189 The ``-c`` switches are compatible with one another, except that 3190 the ``-c0`` switch disables all other comment formatting 3191 switches. 3192 3193 3194 .. _General_Text_Layout_Control: 3195 3196 General Text Layout Control 3197 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3198 3199 These switches allow control over line length and indentation. 3200 3201 .. index:: -M (gnatpp) 3202 3203 :samp:`-M{nnn}` 3204 Maximum line length, `nnn` from 32...256, the default value is 79 3205 3206 3207 .. index:: -i (gnatpp) 3208 3209 :samp:`-i{nnn}` 3210 Indentation level, `nnn` from 1...9, the default value is 3 3211 3212 3213 .. index:: -cl (gnatpp) 3214 3215 :samp:`-cl{nnn}` 3216 Indentation level for continuation lines (relative to the line being 3217 continued), `nnn` from 1...9. 3218 The default 3219 value is one less than the (normal) indentation level, unless the 3220 indentation is set to 1 (in which case the default value for continuation 3221 line indentation is also 1) 3222 3223 3224 .. _Other_Formatting_Options: 3225 3226 Other Formatting Options 3227 ^^^^^^^^^^^^^^^^^^^^^^^^ 3228 3229 These switches control other formatting not listed above. 3230 3231 .. index:: --decimal-grouping (gnatpp) 3232 3233 :samp:`--decimal-grouping={n}` 3234 Put underscores in decimal literals (numeric literals without a base) 3235 every `n` characters. If a literal already has one or more 3236 underscores, it is not modified. For example, with 3237 `--decimal-grouping=3`, `1000000` will be changed to 3238 `1_000_000`. 3239 3240 3241 .. index:: --based-grouping (gnatpp) 3242 3243 :samp:`--based-grouping={n}` 3244 Same as `--decimal-grouping`, but for based literals. For 3245 example, with `--based-grouping=4`, `16#0001FFFE#` will be 3246 changed to `16#0001_FFFE#`. 3247 3248 3249 .. index:: --split-line-before-op (gnatpp) 3250 3251 :samp:`--split-line-before-op` 3252 If it is necessary to split a line at a binary operator, by default 3253 the line is split after the operator. With this option, it is split 3254 before the operator. 3255 3256 3257 .. index:: --RM-style-spacing (gnatpp) 3258 3259 :samp:`--RM-style-spacing` 3260 Do not insert an extra blank before various occurrences of 3261 '(' and ':'. This also turns off alignment. 3262 3263 3264 .. index:: -ff (gnatpp) 3265 3266 :samp:`-ff` 3267 Insert a Form Feed character after a pragma Page. 3268 3269 3270 .. index:: --call_threshold (gnatpp) 3271 3272 :samp:`--call_threshold={nnn}` 3273 If the number of parameter associations is greater than `nnn` and if at 3274 least one association uses named notation, start each association from 3275 a new line. If `nnn` is 0, no check for the number of associations 3276 is made; this is the default. 3277 3278 3279 .. index:: --par_threshold (gnatpp) 3280 3281 :samp:`--par_threshold={nnn}` 3282 If the number of parameter specifications is greater than `nnn` 3283 (or equal to `nnn` in case of a function), start each specification from 3284 a new line. This feature is disabled by default. 3285 3286 3287 .. _Setting_the_Source_Search_Path: 3288 3289 Setting the Source Search Path 3290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3291 3292 To define the search path for the input source file, *gnatpp* 3293 uses the same switches as the GNAT compiler, with the same effects: 3294 3295 .. index:: -I (gnatpp) 3296 3297 3298 :samp:`-I{dir}` 3299 3300 .. index:: -I- (gnatpp) 3301 3302 :samp:`-I-` 3303 3304 .. index:: -gnatec (gnatpp) 3305 3306 :samp:`-gnatec={path}` 3307 3308 3309 .. _Output_File_Control-gnatpp: 3310 3311 Output File Control 3312 ^^^^^^^^^^^^^^^^^^^ 3313 3314 By default the output is sent to a file whose name is obtained by appending 3315 the :file:`.pp` suffix to the name of the input file. 3316 If the file with this name already exists, it is overwritten. 3317 Thus if the input file is :file:`my_ada_proc.adb` then 3318 *gnatpp* will produce :file:`my_ada_proc.adb.pp` 3319 as output file. 3320 The output may be redirected by the following switches: 3321 3322 3323 .. index:: --output-dir (gnatpp) 3324 3325 :samp:`--output-dir={dir}` 3326 Generate output file in directory :file:`dir` with the same name as the input 3327 file. If :file:`dir` is the same as the directory containing the input file, 3328 the input file is not processed; use ``-rnb`` 3329 if you want to update the input file in place. 3330 3331 3332 .. index:: -pipe (gnatpp) 3333 3334 :samp:`-pipe` 3335 Send the output to `Standard_Output` 3336 3337 3338 .. index:: -o (gnatpp) 3339 3340 :samp:`-o {output_file}` 3341 Write the output into `output_file`. 3342 If `output_file` already exists, *gnatpp* terminates without 3343 reading or processing the input file. 3344 3345 3346 .. index:: -of (gnatpp) 3347 3348 :samp:`-of {output_file}` 3349 Write the output into `output_file`, overwriting the existing file 3350 (if one is present). 3351 3352 3353 .. index:: -r (gnatpp) 3354 3355 :samp:`-r` 3356 Replace the input source file with the reformatted output, and copy the 3357 original input source into the file whose name is obtained by appending the 3358 :file:`.npp` suffix to the name of the input file. 3359 If a file with this name already exists, *gnatpp* terminates without 3360 reading or processing the input file. 3361 3362 3363 .. index:: -rf (gnatpp) 3364 3365 :samp:`-rf` 3366 Like ``-r`` except that if the file with the specified name 3367 already exists, it is overwritten. 3368 3369 3370 .. index:: -rnb (gnatpp) 3371 3372 :samp:`-rnb` 3373 Replace the input source file with the reformatted output without 3374 creating any backup copy of the input source. 3375 3376 3377 .. index:: --eol (gnatpp) 3378 3379 :samp:`--eol={xxx}` 3380 Specifies the line-ending style of the reformatted output file. The `xxx` 3381 string specified with the switch may be: 3382 3383 * *dos* - MS DOS style, lines end with CR LF characters* 3384 * *crlf* - the same as *dos* 3385 * *unix* - UNIX style, lines end with LF character* 3386 * *lf* - the same as *unix* 3387 3388 .. index:: -W (gnatpp) 3389 3390 :samp:`-W{e}` 3391 Specify the wide character encoding method for the input and output files. 3392 `e` is one of the following: 3393 3394 * *h* - Hex encoding 3395 3396 * *u* - Upper half encoding 3397 3398 * *s* - Shift/JIS encoding 3399 3400 * *e* - EUC encoding 3401 3402 * *8* - UTF-8 encoding 3403 3404 * *b* - Brackets encoding (default value) 3405 3406 Options ``-o`` and ``-of`` are allowed only if the call to gnatpp 3407 contains only one file to reformat. 3408 3409 Option ``--eol`` and ``-W`` cannot be used together 3410 with the ``-pipe`` option. 3411 3412 3413 .. _Other_gnatpp_Switches: 3414 3415 Other `gnatpp` Switches 3416 ^^^^^^^^^^^^^^^^^^^^^^^ 3417 3418 The additional *gnatpp* switches are defined in this subsection. 3419 3420 3421 .. index:: --version (gnatpp) 3422 3423 :samp:`--version` 3424 Display copyright and version, then exit disregarding all other options. 3425 3426 3427 .. index:: --help (gnatpp) 3428 3429 :samp:`--help` 3430 Display usage, then exit disregarding all other options. 3431 3432 3433 .. index:: -P (gnatpp) 3434 3435 :samp:`-P {file}` 3436 Indicates the name of the project file that describes the set of sources 3437 to be processed. The exact set of argument sources depends on other options 3438 specified; see below. 3439 3440 3441 .. index:: -U (gnatpp) 3442 3443 :samp:`-U` 3444 If a project file is specified and no argument source is explicitly 3445 specified (either directly or by means of ``-files`` option), process 3446 all the units of the closure of the argument project. Otherwise this option 3447 has no effect. 3448 3449 3450 :samp:`-U {main_unit}` 3451 If a project file is specified and no argument source is explicitly 3452 specified (either directly or by means of ``-files`` option), process 3453 the closure of units rooted at `main_unit`. Otherwise this option 3454 has no effect. 3455 3456 3457 .. index:: -X (gnatpp) 3458 3459 :samp:`-X{name}={value}` 3460 Indicates that external variable `name` in the argument project 3461 has the value `value`. Has no effect if no project is specified as 3462 tool argument. 3463 3464 3465 .. index:: --RTS (gnatpp) 3466 3467 :samp:`--RTS={rts-path}` 3468 Specifies the default location of the runtime library. Same meaning as the 3469 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). 3470 3471 3472 .. index:: --incremental (gnatpp) 3473 3474 :samp:`--incremental` 3475 Incremental processing on a per-file basis. Source files are only 3476 processed if they have been modified, or if files they depend on have 3477 been modified. This is similar to the way gnatmake/gprbuild only 3478 compiles files that need to be recompiled. A project file is required 3479 in this mode, and the gnat driver (as in *gnat pretty*) is not 3480 supported. 3481 3482 3483 .. index:: --pp-off (gnatpp) 3484 3485 :samp:`--pp-off={xxx}` 3486 Use `--xxx` as the command to turn off pretty printing, instead 3487 of the default `--!pp off`. 3488 3489 3490 .. index:: --pp-on (gnatpp) 3491 3492 :samp:`--pp-on={xxx}` 3493 Use `--xxx` as the command to turn pretty printing back on, instead 3494 of the default `--!pp on`. 3495 3496 3497 .. index:: -files (gnatpp) 3498 3499 :samp:`-files {filename}` 3500 Take the argument source files from the specified file. This file should be an 3501 ordinary text file containing file names separated by spaces or 3502 line breaks. You can use this switch more than once in the same call to 3503 *gnatpp*. You also can combine this switch with an explicit list of 3504 files. 3505 3506 3507 .. index:: -j (gnatpp) 3508 3509 :samp:`-j{n}` 3510 Without ``--incremental``, use `n` processes to carry out the 3511 tree creations (internal representations of the argument sources). On 3512 a multiprocessor machine this speeds up processing of big sets of 3513 argument sources. If `n` is 0, then the maximum number of parallel 3514 tree creations is the number of core processors on the platform. This 3515 option cannot be used together with ``-r``, 3516 ``-rf`` or 3517 ``-rnb`` option. 3518 3519 With ``--incremental``, use `n` *gnatpp* processes to 3520 perform pretty-printing in parallel. `n` = 0 means the same as 3521 above. In this case, ``-r``, 3522 ``-rf`` or 3523 ``-rnb`` options are allowed. 3524 3525 .. index:: -t (gnatpp) 3526 3527 3528 :samp:`-t` 3529 Print out execution time. 3530 3531 3532 .. index:: -v (gnatpp) 3533 3534 :samp:`-v` 3535 Verbose mode 3536 3537 3538 .. index:: -q (gnatpp) 3539 3540 :samp:`-q` 3541 Quiet mode 3542 3543 If a project file is specified and no argument source is explicitly 3544 specified (either directly or by means of ``-files`` option), and no 3545 ``-U`` is specified, then the set of processed sources is 3546 all the immediate units of the argument project. 3547 3548 3549 .. _Formatting_Rules: 3550 3551 Formatting Rules 3552 ---------------- 3553 3554 The following subsections show how *gnatpp* treats white space, 3555 comments, program layout, and name casing. 3556 They provide detailed descriptions of the switches shown above. 3557 3558 3559 .. _Disabling_Pretty_Printing: 3560 3561 Disabling Pretty Printing 3562 ^^^^^^^^^^^^^^^^^^^^^^^^^ 3563 3564 Pretty printing is highly heuristic in nature, and sometimes doesn't 3565 do exactly what you want. If you wish to format a certain region of 3566 code by hand, you can turn off pretty printing in that region by 3567 surrounding it with special comments that start with ``--!pp off`` 3568 and ``--!pp on``. The text in that region will then be reproduced 3569 verbatim in the output with no formatting. 3570 3571 To disable pretty printing for the whole file, put ``--!pp off`` at 3572 the top, with no following ``--!pp on``. 3573 3574 The comments must appear on a line by themselves, with nothing 3575 preceding except spaces. The initial text of the comment must be 3576 exactly ``--!pp off`` or ``--!pp on`` (case sensitive), but may 3577 be followed by arbitrary additional text. For example: 3578 3579 .. code-block:: ada 3580 3581 package Interrupts is 3582 --!pp off -- turn off pretty printing so "Interrupt_Kind" lines up 3583 type Interrupt_Kind is 3584 (Asynchronous_Interrupt_Kind, 3585 Synchronous_Interrupt_Kind, 3586 Green_Interrupt_Kind); 3587 --!pp on -- reenable pretty printing 3588 ... 3589 3590 You can specify different comment strings using the ``--pp-off`` 3591 and ``--pp-on`` switches. For example, if you say: 3592 3593 :: 3594 3595 $ gnatpp --pp-off=' pp-' *.ad? 3596 3597 then gnatpp will recognize comments of the form 3598 ``-- pp-`` instead of ``--!pp off`` for disabling pretty 3599 printing. Note that the leading ``--`` of the comment is not 3600 included in the argument to these switches. 3601 3602 3603 .. _White_Space_and_Empty_Lines: 3604 3605 White Space and Empty Lines 3606 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3607 3608 *gnatpp* does not have an option to control space characters. 3609 It will add or remove spaces according to the style illustrated by the 3610 examples in the :title:`Ada Reference Manual`. 3611 The output file will contain no lines with trailing white space. 3612 3613 By default, a sequence of one or more blank lines in the input is 3614 converted to a single blank line in the output; multiple blank lines 3615 are squeezed down to one. 3616 The ``--preserve-blank-lines`` option 3617 turns off the squeezing; each blank line in the input is copied 3618 to the output. 3619 The ``--insert-blank-lines`` option 3620 causes additional blank lines to be inserted if not already 3621 present in the input (e.g. between bodies). 3622 3623 3624 .. _Formatting_Comments: 3625 3626 Formatting Comments 3627 ^^^^^^^^^^^^^^^^^^^ 3628 3629 Comments in Ada code are of two kinds: 3630 3631 * a *whole-line comment*, which appears by itself (possibly preceded by 3632 white space) on a line 3633 3634 * an *end-of-line comment*, which follows some other Ada code on 3635 the same line. 3636 3637 A whole-line comment is indented according to the surrounding code, 3638 with some exceptions. 3639 Comments that start in column 1 are kept there. 3640 If possible, comments are not moved so far to the right that the maximum 3641 line length is exceeded. 3642 The ``-c0`` option 3643 turns off comment formatting. 3644 Special-form comments such as SPARK-style ``--#...`` are left alone. 3645 3646 For an end-of-line comment, *gnatpp* tries to leave the same 3647 number of spaces between the end of the preceding Ada code and the 3648 beginning of the comment as appear in the original source. 3649 3650 The ``-c3`` switch 3651 (GNAT style comment beginning) has the following 3652 effect: 3653 3654 * For each whole-line comment that does not end with two hyphens, 3655 *gnatpp* inserts spaces if necessary after the starting two hyphens 3656 to ensure that there are at least two spaces between these hyphens and the 3657 first non-blank character of the comment. 3658 3659 The ``-c4`` switch specifies that 3660 whole-line comments that form a paragraph will be filled in typical 3661 word processor style (that is, moving words between lines to make the 3662 lines other than the last similar in length ). 3663 3664 The ``--comments-only`` switch specifies that only the comments 3665 are formatted; the rest of the program text is left alone. The 3666 comments are formatted according to the -c3 and -c4 switches; other 3667 formatting switches are ignored. For example, 3668 ``--comments-only -c4`` means to fill comment paragraphs, and do nothing else. 3669 Likewise, 3670 ``--comments-only -c3`` ensures comments start with at least two 3671 spaces after `--`, and ``--comments-only -c3 -c4`` does 3672 both. If ``--comments-only`` is given without ``-c3`` or 3673 ``-c4``, then gnatpp doesn't format anything. 3674 3675 3676 .. _Name_Casing: 3677 3678 Name Casing 3679 ^^^^^^^^^^^ 3680 3681 *gnatpp* always converts the usage occurrence of a (simple) name to 3682 the same casing as the corresponding defining identifier. 3683 3684 You control the casing for defining occurrences via the 3685 ``-n`` switch. 3686 With ``-nD`` ('as declared', which is the default), 3687 defining occurrences appear exactly as in the source file 3688 where they are declared. 3689 The other values for this switch -- 3690 ``-nU``, 3691 ``-nL``, 3692 ``-nM`` -- 3693 result in 3694 upper, lower, or mixed case, respectively. 3695 If *gnatpp* changes the casing of a defining 3696 occurrence, it analogously changes the casing of all the 3697 usage occurrences of this name. 3698 3699 If the defining occurrence of a name is not in the source compilation unit 3700 currently being processed by *gnatpp*, the casing of each reference to 3701 this name is changed according to the value of the ``-n`` 3702 switch (subject to the dictionary file mechanism described below). 3703 Thus *gnatpp* acts as though the ``-n`` switch 3704 had affected the 3705 casing for the defining occurrence of the name. 3706 3707 The options 3708 :samp:`-a{x}`, 3709 :samp:`-k{x}`, 3710 :samp:`-ne{x}`, 3711 :samp:`-nt{x}`, 3712 :samp:`-nn{x}`, and 3713 :samp:`-p{x}` 3714 allow finer-grained control over casing for 3715 attributes, keywords, enumeration literals, 3716 types, named numbers and pragmas, respectively. 3717 :samp:`-nt{x}` covers subtypes and 3718 task and protected bodies as well. 3719 3720 Some names may need to be spelled with casing conventions that are not 3721 covered by the upper-, lower-, and mixed-case transformations. 3722 You can arrange correct casing by placing such names in a 3723 *dictionary file*, 3724 and then supplying a ``-D`` switch. 3725 The casing of names from dictionary files overrides 3726 any ``-n`` switch. 3727 3728 To handle the casing of Ada predefined names and the names from GNAT libraries, 3729 *gnatpp* assumes a default dictionary file. 3730 The name of each predefined entity is spelled with the same casing as is used 3731 for the entity in the :title:`Ada Reference Manual` (usually mixed case). 3732 The name of each entity in the GNAT libraries is spelled with the same casing 3733 as is used in the declaration of that entity. 3734 3735 The ``-D-`` switch suppresses the use of 3736 the default dictionary file. Instead, the casing for predefined and 3737 GNAT-defined names will be established by the 3738 ``-n`` switch or explicit dictionary files. For 3739 example, by default the names `Ada.Text_IO` and 3740 `GNAT.OS_Lib` will appear as just shown, even in the presence of 3741 a ``-nU`` switch. To ensure that even 3742 such names are rendered in uppercase, additionally supply the 3743 -D- switch (or else place these names 3744 in upper case in a dictionary file). 3745 3746 A dictionary file is a plain text file; each line in this file can be 3747 either a blank line (containing only space characters), an Ada comment 3748 line, or the specification of exactly one *casing schema*. 3749 3750 A casing schema is a string that has the following syntax: 3751 3752 :: 3753 3754 `casing_schema` ::= `identifier` | `simple_identifier` 3755 3756 `simple_identifier` ::= `letter`{`letter_or_digit`} 3757 3758 3759 (See :title:`Ada Reference Manual`, Section 2.3) for the definition of the 3760 `identifier` lexical element and the `letter_or_digit` category.) 3761 3762 The casing schema string can be followed by white space and/or an Ada-style 3763 comment; any amount of white space is allowed before the string. 3764 3765 If a dictionary file is passed as 3766 the value of a :samp:`-D{file}` switch 3767 then for every 3768 simple name and every identifier, *gnatpp* checks if the dictionary 3769 defines the casing for the name or for some of its parts (the term 'subword' 3770 is used below to denote the part of a name which is delimited by '_' or by 3771 the beginning or end of the word and which does not contain any '_' inside): 3772 3773 * if the whole name is in the dictionary, *gnatpp* uses for this name 3774 the casing defined by the dictionary; no subwords are checked for this word 3775 3776 * for every subword *gnatpp* checks if the dictionary contains the 3777 corresponding string of the form `*`simple_identifier`*`, 3778 and if it does, the casing of this `simple_identifier` is used 3779 for this subword 3780 3781 * if the whole name does not contain any '_' inside, and if for this name 3782 the dictionary contains two entries - one of the form `identifier`, 3783 and another - of the form *`simple_identifier`*, then the first one 3784 is applied to define the casing of this name 3785 3786 * if more than one dictionary file is passed as *gnatpp* switches, each 3787 dictionary adds new casing exceptions and overrides all the existing casing 3788 exceptions set by the previous dictionaries 3789 3790 * when *gnatpp* checks if the word or subword is in the dictionary, 3791 this check is not case sensitive 3792 3793 For example, suppose we have the following source to reformat: 3794 3795 .. code-block:: ada 3796 3797 procedure test is 3798 name1 : integer := 1; 3799 name4_name3_name2 : integer := 2; 3800 name2_name3_name4 : Boolean; 3801 name1_var : Float; 3802 begin 3803 name2_name3_name4 := name4_name3_name2 > name1; 3804 end; 3805 3806 And suppose we have two dictionaries: 3807 3808 :: 3809 3810 *dict1:* 3811 NAME1 3812 *NaMe3* 3813 *Name1* 3814 3815 *dict2:* 3816 *NAME3* 3817 3818 If *gnatpp* is called with the following switches: 3819 3820 :: 3821 3822 $ gnatpp -nM -D dict1 -D dict2 test.adb 3823 3824 then we will get the following name casing in the *gnatpp* output: 3825 3826 3827 .. code-block:: ada 3828 3829 procedure Test is 3830 NAME1 : Integer := 1; 3831 Name4_NAME3_Name2 : Integer := 2; 3832 Name2_NAME3_Name4 : Boolean; 3833 Name1_Var : Float; 3834 begin 3835 Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; 3836 end Test; 3837 3838 3839.. only:: PRO or GPL 3840 3841 .. _The_Body_Stub_Generator_gnatstub: 3842 3843 The Body Stub Generator *gnatstub* 3844 ================================== 3845 3846 .. index:: ! gnatstub 3847 3848 *gnatstub* creates empty but compilable bodies 3849 for library unit declarations, and empty but compilable 3850 subunit for body stubs. 3851 3852 To create a body or a subunit, *gnatstub* invokes the Ada 3853 compiler and generates and uses the ASIS tree for the input source; 3854 thus the input must be legal Ada code, and the tool should have all the 3855 information needed to compile the input source. To provide this information, 3856 you may specify as a tool parameter the project file the input source belongs to 3857 (or you may call *gnatstub* 3858 through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`). 3859 Another possibility is to specify the source search 3860 path and needed configuration files in ``-cargs`` section of *gnatstub* 3861 call, see the description of the *gnatstub* switches below. 3862 3863 If the *gnatstub* argument source contains preprocessing directives 3864 then the needed options should be provided to run preprocessor as a part of 3865 the *gnatstub* call, and the generated body stub will correspond to 3866 the preprocessed source. 3867 3868 By default, all the program unit bodies generated by `gnatstub` 3869 raise the predefined `Program_Error` exception, which will catch 3870 accidental calls of generated stubs. This behavior can be changed with 3871 option ``--no-exception`` (see below). 3872 3873 .. _Running_gnatstub: 3874 3875 Running *gnatstub* 3876 ------------------ 3877 3878 *gnatstub* invocation has the following form: 3879 3880 :: 3881 3882 $ gnatstub [`switches`] `filename` [-cargs `gcc_switches`] 3883 3884 where 3885 3886 * *filename* 3887 is the name of the source file that contains a library unit declaration 3888 for which a body must be created or a library unit body for which subunits 3889 must be created for the body stubs declared in this body. 3890 The file name may contain the path information. 3891 If the name does not follow GNAT file naming conventions and a set 3892 of seitches does not contain a project file that defines naming 3893 conventions, the name of the body file must 3894 be provided 3895 explicitly as the value of the :samp:`-o{body-name}` option. 3896 If the file name follows the GNAT file naming 3897 conventions and the name of the body file is not provided, 3898 *gnatstub* 3899 takes the naming conventions for the generated source from the 3900 project file provided as a parameter of ``-P`` switch if any, 3901 or creates the name file to generate using the standard GNAT 3902 naming conventions. 3903 3904 * *gcc_switches* is a list of switches for *gcc*. 3905 They will be passed on to all compiler invocations made by 3906 *gnatstub* to generate the ASIS trees. Here you can provide 3907 ``-I`` switches to form the source search path, 3908 use the ``-gnatec`` switch to set the configuration file, 3909 use the ``-gnat05`` switch if sources should be compiled in 3910 Ada 2005 mode etc. 3911 3912 * *switches* 3913 is an optional sequence of switches as described in the next section 3914 3915 3916 .. _Switches_for_gnatstub: 3917 3918 Switches for *gnatstub* 3919 ----------------------- 3920 3921 .. index:: --version (gnatstub) 3922 3923 :samp:`--version` 3924 Display Copyright and version, then exit disregarding all other options. 3925 3926 3927 .. index:: --help (gnatstub) 3928 3929 :samp:`--help` 3930 Display usage, then exit disregarding all other options. 3931 3932 3933 .. index:: -P (gnatstub) 3934 3935 :samp:`-P {file}` 3936 Indicates the name of the project file that describes the set of sources 3937 to be processed. 3938 3939 3940 .. index:: -X (gnatstub) 3941 3942 :samp:`-X{name}={value}` 3943 Indicates that external variable `name` in the argument project 3944 has the value `value`. Has no effect if no project is specified as 3945 tool argument. 3946 3947 3948 .. index:: --RTS (gnatstub) 3949 3950 :samp:`--RTS={rts-path}` 3951 Specifies the default location of the runtime library. Same meaning as the 3952 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). 3953 3954 3955 .. index:: --subunits (gnatstub) 3956 3957 :samp:`--subunits` 3958 Generate subunits for body stubs. If this switch is specified, 3959 *gnatstub* expects a library unit body as an agrument file, 3960 otherwise a library unit declaration is expected. If a body stub 3961 already has a corresponding subunit, *gnatstub* does not 3962 generate anything for it. 3963 3964 3965 .. index:: -f (gnatstub) 3966 3967 :samp:`-f` 3968 If the destination directory already contains a file with the name of the 3969 body file 3970 for the argument spec file, replace it with the generated body stub. 3971 This switch cannot be used together with ``--subunits``. 3972 3973 3974 .. index:: -hs (gnatstub) 3975 3976 :samp:`-hs` 3977 Put the comment header (i.e., all the comments preceding the 3978 compilation unit) from the source of the library unit declaration 3979 into the body stub. 3980 3981 3982 .. index:: -hg (gnatstub) 3983 3984 :samp:`-hg` 3985 Put a sample comment header into the body stub. 3986 3987 3988 .. index:: --header-file (gnatstub) 3989 3990 :samp:`--header-file={filename}` 3991 Use the content of the file as the comment header for a generated body stub. 3992 3993 3994 .. index:: -IDIR (gnatstub) 3995 .. index:: -I- (gnatstub) 3996 3997 :samp:`-I{DIR}`, :samp:`-I-` 3998 These switches have the same meaning as in calls to 3999 *gcc*. 4000 They define the source search path in the call to 4001 *gcc* issued 4002 by *gnatstub* to compile an argument source file. 4003 4004 4005 .. index:: -gnatec (gnatstub) 4006 4007 :samp:`-gnatec{PATH}` 4008 This switch has the same meaning as in calls to *gcc*. 4009 It defines the additional configuration file to be passed to the call to 4010 *gcc* issued 4011 by *gnatstub* to compile an argument source file. 4012 4013 4014 .. index:: -gnatyM (gnatstub) 4015 4016 :samp:`-gnatyM{n}` 4017 (`n` is a non-negative integer). Set the maximum line length that is 4018 allowed in a source file. The default is 79. The maximum value that can be 4019 specified is 32767. Note that in the special case of configuration 4020 pragma files, the maximum is always 32767 regardless of whether or 4021 not this switch appears. 4022 4023 4024 .. index:: -gnaty (gnatstub) 4025 4026 :samp:`-gnaty{n}` 4027 (`n` is a non-negative integer from 1 to 9). Set the indentation level in 4028 the generated body sample to `n`. 4029 The default indentation is 3. 4030 4031 4032 .. index:: -gnatyo (gnatstub) 4033 4034 :samp:`-gnatyo` 4035 Order local bodies alphabetically. (By default local bodies are ordered 4036 in the same way as the corresponding local specs in the argument spec file.) 4037 4038 4039 .. index:: -i (gnatstub) 4040 4041 :samp:`-i{n}` 4042 Same as :samp:`-gnaty{n}`` 4043 4044 4045 .. index:: -k (gnatstub) 4046 4047 :samp:`-k` 4048 Do not remove the tree file (i.e., the snapshot of the compiler internal 4049 structures used by *gnatstub*) after creating the body stub. 4050 4051 4052 .. index:: -l (gnatstub) 4053 4054 :samp:`-l{n}` 4055 Same as ``-gnatyM`n``` 4056 4057 4058 .. index:: --no-exception (gnatstub) 4059 4060 :samp:`--no-exception` 4061 Avoid raising PROGRAM_ERROR in the generated bodies of program unit stubs. 4062 This is not always possible for function stubs. 4063 4064 4065 .. index:: --no-local-header (gnatstub) 4066 4067 :samp:`--no-local-header` 4068 Do not place local comment header with unit name before body stub for a 4069 unit. 4070 4071 4072 .. index:: -o (gnatstub) 4073 4074 :samp:`-o {body-name}` 4075 Body file name. This should be set if the argument file name does not 4076 follow 4077 the GNAT file naming 4078 conventions. If this switch is omitted the default name for the body will be 4079 obtained 4080 from the argument file name according to the GNAT file naming conventions. 4081 4082 4083 .. index:: --dir (gnatstub) 4084 4085 :samp:`--dir={dir-name}` 4086 The path to the directory to place the generated files into. 4087 If this switch is not set, the generated library unit body is 4088 placed in the current directory, and generated sununits - 4089 in the directory where the argument body is located. 4090 4091 4092 .. index:: -W (gnatstub) 4093 4094 :samp:`-W{e}` 4095 Specify the wide character encoding method for the output body file. 4096 `e` is one of the following: 4097 4098 ==== ================================== 4099 *h* Hex encoding 4100 *u* Upper half encoding 4101 *s* Shift/JIS encoding 4102 *e* EUC encoding 4103 *8* UTF-8 encoding 4104 *b* Brackets encoding (default value) 4105 ==== ================================== 4106 4107 4108 .. index:: -q (gnatstub) 4109 4110 :samp:`-q` 4111 Quiet mode: do not generate a confirmation when a body is 4112 successfully created, and do not generate a message when a body is not 4113 required for an 4114 argument unit. 4115 4116 4117 .. index:: -r (gnatstub) 4118 4119 :samp:`-r` 4120 Reuse the tree file (if it exists) instead of creating it. Instead of 4121 creating the tree file for the library unit declaration, *gnatstub* 4122 tries to find it in the current directory and use it for creating 4123 a body. If the tree file is not found, no body is created. This option 4124 also implies ``-k``, whether or not 4125 the latter is set explicitly. 4126 4127 4128 .. index:: -t (gnatstub) 4129 4130 :samp:`-t` 4131 Overwrite the existing tree file. If the current directory already 4132 contains the file which, according to the GNAT file naming rules should 4133 be considered as a tree file for the argument source file, 4134 *gnatstub* 4135 will refuse to create the tree file needed to create a sample body 4136 unless this option is set. 4137 4138 4139 .. index:: -v (gnatstub) 4140 4141 :samp:`-v` 4142 Verbose mode: generate version information. 4143 4144 4145 4146.. only:: PRO or GPL 4147 4148 .. _The_Unit_Test_Generator_gnattest: 4149 4150 The Unit Test Generator *gnattest* 4151 ================================== 4152 4153 .. index:: ! gnattest 4154 4155 *gnattest* is an ASIS-based utility that creates unit-test skeletons 4156 as well as a test driver infrastructure (harness). *gnattest* creates 4157 a skeleton for each visible subprogram in the packages under consideration when 4158 they do not exist already. 4159 4160 The user can choose to generate a single test driver 4161 that will run all individual tests, or separate test drivers for each test. The 4162 second option allows much greater flexibility in test execution environment, 4163 allows to benefit from parallel tests execution to increase performance, and 4164 provides stubbing support. 4165 4166 *gnattest* also has a mode of operation where it acts as the test 4167 aggregator when multiple test executables must be run, in particular when 4168 the separate test drivers were generated. In this mode it handles individual 4169 tests execution and upon completion reports the summary results of the test 4170 run. 4171 4172 In order to process source files from a project, *gnattest* has to 4173 semantically analyze the sources. Therefore, test skeletons can only be 4174 generated for legal Ada units. If a unit is dependent on other units, 4175 those units should be among the source files of the project or of other projects 4176 imported by this one. 4177 4178 Generated skeletons and harnesses are based on the AUnit testing framework. 4179 AUnit is an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit 4180 for Java or CppUnit for C++. While it is advised that gnattest users read 4181 the AUnit manual, deep knowledge of AUnit is not necessary for using *gnattest*. 4182 For correct operation of *gnattest*, AUnit should be installed and 4183 aunit.gpr must be on the project path. Except for some special circumstances 4184 (e.g. a custom run-time is used), this should normally be the case out of the box. 4185 4186 4187 .. _Running_gnattest: 4188 4189 Running *gnattest* 4190 ------------------ 4191 4192 There are two ways of running *gnattest*. 4193 4194 .. _Framework_Generation_Mode: 4195 4196 Framework Generation Mode 4197 ^^^^^^^^^^^^^^^^^^^^^^^^^ 4198 4199 In this mode *gnattest* has the following command-line interface: 4200 4201 :: 4202 4203 $ gnattest `-Pprojname` [`switches`] [`filename`] [-cargs `gcc_switches`] 4204 4205 where 4206 4207 * :samp:`-P{projname}` 4208 specifies the project defining the location of source files. When no 4209 file names are provided on the command line, all sources in the project 4210 are used as input. This switch is required. 4211 4212 * :samp:`{filename}` 4213 is the name of the source file containing the library unit package declaration 4214 for which a test package will be created. The file name may be given with a 4215 path. 4216 4217 * :samp:`{switches}` 4218 is an optional sequence of switches as described below. 4219 4220 * :samp:`{gcc_switches}` 4221 is a list of additional switches for 4222 *gcc* that will be passed to all compiler invocations 4223 made by *gnattest* to generate a set of ASIS trees. 4224 4225 4226 *gnattest* results can be found in two different places. 4227 4228 * *automatic harness*: 4229 This is the harness code, which is located by default in 4230 "gnattest/harness" directory created in the object directory of 4231 the main project file. All of this code is generated completely 4232 automatically and can be destroyed and regenerated at will, with the 4233 exception of the file *gnattest_common.gpr*, which is created if absent, 4234 but never overwritten. It is not recommended to modify other files 4235 manually, since these modifications will be lost if *gnattest* is re-run. 4236 The entry point in the harness code is 4237 the project file named *test_driver.gpr*. Tests can be compiled and run 4238 using a command such as: 4239 4240 :: 4241 4242 $ gprbuild -P<harness-dir>/test_driver 4243 4244 Note that if you need to adjust any options used to compile the harness, 4245 you can do so by editing the file *gnattest_common.gpr*. 4246 4247 * *actual unit test skeletons*: 4248 A test skeleton for each visible subprogram is created in a separate file, if it 4249 doesn't exist already. By default, those separate test files are located in a 4250 "gnattest/tests" directory that is created in the object directory of 4251 corresponding project file. For example, if a source file my_unit.ads in 4252 directory src contains a visible subprogram Proc, then the corresponding unit 4253 test will be found in file src/tests/my_unit-test_data-tests.adb and will be 4254 called Test_Proc_<code>. <code> is a signature encoding used to differentiate 4255 test names in case of overloading. 4256 4257 Note that if the project already has both my_unit.ads and my_unit-test_data.ads, 4258 this will cause a name conflict with the generated test package. 4259 4260 4261 .. _Test_Execution_Mode: 4262 4263 Test Execution Mode 4264 ^^^^^^^^^^^^^^^^^^^ 4265 4266 In this mode *gnattest* has a the following command-line interface: 4267 4268 :: 4269 4270 $ gnattest `test_drivers.list` [`switches`] 4271 4272 where 4273 4274 * :samp:`{test_drivers.list}` 4275 is the name of the text file containing the list of executables to treat as 4276 test drivers. This file is automatically generated by gnattest, but can be 4277 hand-edited to add or remove tests. This switch is required. 4278 4279 4280 * :samp:`{switches}` 4281 is an optional sequence of switches as described below. 4282 4283 4284 .. _Switches_for_gnattest_in_framework_generation_mode: 4285 4286 Switches for *gnattest* in framework generation mode 4287 ---------------------------------------------------- 4288 4289 .. index:: -q (gnattest) 4290 4291 :samp:`-q` 4292 Quiet mode: suppresses noncritical output messages. 4293 4294 4295 .. index:: -v (gnattest) 4296 4297 :samp:`-v` 4298 Verbose mode: produces additional output about the execution of the tool. 4299 When specified alone on the command line, prints tool version and exits. 4300 4301 4302 .. index:: -r (gnattest) 4303 4304 :samp:`-r` 4305 Recursively considers all sources from all projects. 4306 4307 4308 .. index:: -X (gnattest) 4309 4310 :samp:`-X{name}={value}` 4311 Indicate that external variable `name` has the value `value`. 4312 4313 4314 .. index:: --RTS (gnattest) 4315 4316 :samp:`--RTS={rts-path}` 4317 Specifies the default location of the runtime library. Same meaning as the 4318 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). For restricted 4319 profiles, *gnattest* takes into account the run-time limitations when 4320 generating the harness. 4321 4322 4323 .. index:: --additional-tests (gnattest) 4324 4325 :samp:`--additional-tests={projname}` 4326 Sources described in `projname` are considered potential additional 4327 manual tests to be added to the test suite. 4328 4329 4330 .. index:: --harness-only (gnattest) 4331 4332 :samp:`--harness-only` 4333 When this option is given, *gnattest* creates a harness for all 4334 sources, treating them as test packages. 4335 4336 4337 .. index:: --separate-drivers (gnattest) 4338 4339 :samp:`--separate-drivers` 4340 Generates a separate test driver for each test, rather than a single 4341 executable incorporating all tests. 4342 4343 4344 .. index:: --stub (gnattest) 4345 4346 :samp:`--stub` 4347 Generates the testing framework that uses subsystem stubbing to isolate the 4348 code under test. 4349 4350 4351 .. index:: --harness-dir (gnattest) 4352 4353 :samp:`--harness-dir={dirname}` 4354 Specifies the directory that will hold the harness packages and project file 4355 for the test driver. If the `dirname` is a relative path, it is considered 4356 relative to the object directory of the project file. 4357 4358 4359 .. index:: --tests-dir (gnattest) 4360 4361 :samp:`--tests-dir={dirname}` 4362 All test packages are placed in the `dirname` directory. 4363 If the `dirname` is a relative path, it is considered relative to the object 4364 directory of the project file. When all sources from all projects are taken 4365 recursively from all projects, `dirname` directories are created for each 4366 project in their object directories and test packages are placed accordingly. 4367 4368 4369 .. index:: --subdir (gnattest) 4370 4371 :samp:`--subdir={dirname}` 4372 Test packages are placed in a subdirectory of the corresponding source 4373 directory, with the name `dirname`. Thus, each set of unit tests is located 4374 in a subdirectory of the code under test. If the sources are in separate 4375 directories, each source directory has a test subdirectory named `dirname`. 4376 4377 4378 .. index:: --tests-root (gnattest) 4379 4380 :samp:`--tests-root={dirname}` 4381 The hierarchy of source directories, if any, is recreated in the `dirname` 4382 directory, with test packages placed in directories corresponding to those 4383 of the sources. 4384 If the `dirname` is a relative path, it is considered relative to the object 4385 directory of the project file. When projects are considered recursively, 4386 directory hierarchies of tested sources are 4387 recreated for each project in their object directories and test packages are 4388 placed accordingly. 4389 4390 4391 .. index:: --stubs-dir (gnattest) 4392 4393 :samp:`--stubs-dir={dirname}` 4394 The hierarchy of directories containing stubbed units is recreated in 4395 the `dirname` directory, with stubs placed in directories corresponding to 4396 projects they are derived from. 4397 If the `dirname` is a relative path, it is considered relative to the object 4398 directory of the project file. When projects are considered recursively, 4399 directory hierarchies of stubs are 4400 recreated for each project in their object directories and test packages are 4401 placed accordingly. 4402 4403 4404 .. index:: --validate-type-extensions (gnattest) 4405 4406 :samp:`--validate-type-extensions` 4407 Enables substitution check: run all tests from all parents in order 4408 to check substitutability in accordance with the Liskov substitution principle (LSP). 4409 4410 4411 .. index:: --skeleton-default (gnattest) 4412 4413 :samp:`--skeleton-default={val}` 4414 Specifies the default behavior of generated skeletons. `val` can be either 4415 "fail" or "pass", "fail" being the default. 4416 4417 4418 .. index:: --passed-tests (gnattest) 4419 4420 :samp:`--passed-tests={val}` 4421 Specifies whether or not passed tests should be shown. `val` can be either 4422 "show" or "hide", "show" being the default. 4423 4424 4425 .. index:: --exit-status (gnattest) 4426 4427 :samp:`--exit-status={val}` 4428 Specifies whether or not generated test driver should return failure exit 4429 status if at least one test fails or crashes. `val` can be either 4430 "on" or "off", "off" being the default. 4431 4432 4433 .. index:: --omit-sloc (gnattest) 4434 4435 :samp:`--omit-sloc` 4436 Suppresses comment line containing file name and line number of corresponding 4437 subprograms in test skeletons. 4438 4439 4440 .. index:: --no-command-line (gnattest) 4441 4442 :samp:`--no-command-line` 4443 Don't add command line support to test driver. Note that regardless of this 4444 switch, *gnattest* will automatically refrain from adding command 4445 line support if it detects that the selected run-time doesn't provide 4446 this capability. 4447 4448 4449 .. index:: --separates (gnattest) 4450 4451 :samp:`--separates` 4452 Bodies of all test routines are generated as separates. Note that this mode is 4453 kept for compatibility reasons only and it is not advised to use it due to 4454 possible problems with hash in names of test skeletons when using an 4455 inconsistent casing. Separate test skeletons can be incorporated to monolith 4456 test package with improved hash being used by using ``--transition`` 4457 switch. 4458 4459 4460 .. index:: --transition (gnattest) 4461 4462 :samp:`--transition` 4463 This allows transition from separate test routines to monolith test packages. 4464 All matching test routines are overwritten with contents of corresponding 4465 separates. Note that if separate test routines had any manually added with 4466 clauses they will be moved to the test package body as is and have to be moved 4467 by hand. 4468 4469 4470 .. index:: --test-duration (gnattest) 4471 4472 :samp:`--test-duration` 4473 Adds time measurements for each test in generated test driver. 4474 4475 4476 :samp:`--tests_root`, ``--subdir`` and ``--tests-dir`` switches are mutually exclusive. 4477 4478 4479 .. _Switches_for_gnattest_in_test_execution_mode: 4480 4481 Switches for *gnattest* in test execution mode 4482 ---------------------------------------------- 4483 4484 4485 .. index:: --passed-tests (gnattest) 4486 4487 :samp:`--passed-tests={val}` 4488 Specifies whether or not passed tests should be shown. `val` can be either 4489 "show" or "hide", "show" being the default. 4490 4491 4492 .. index:: --queues (gnattest) 4493 .. index:: -j (gnattest) 4494 4495 :samp:`--queues={n}`, :samp:`-j{n}` 4496 Runs `n` tests in parallel (default is 1). 4497 4498 4499 .. _Project_Attributes_for_gnattest: 4500 4501 Project Attributes for *gnattest* 4502 --------------------------------- 4503 4504 Most of the command-line options can also be passed to the tool by adding 4505 special attributes to the project file. Those attributes should be put in 4506 package **Gnattest**. Here is the list of attributes: 4507 4508 4509 * ``Tests_Root`` 4510 is used to select the same output mode as with the ``--tests-root`` option. 4511 This attribute cannot be used together with ``Subdir`` or ``Tests_Dir``. 4512 4513 * ``Subdir`` 4514 is used to select the same output mode as with the ``--subdir`` option. 4515 This attribute cannot be used together with ``Tests_Root`` or ``Tests_Dir``. 4516 4517 * ``Tests_Dir`` 4518 is used to select the same output mode as with the ``--tests-dir`` option. 4519 This attribute cannot be used together with ``Subdir`` or ``Tests_Root``. 4520 4521 * ``Harness_Dir`` 4522 is used to specify the directory in which to place harness packages and project 4523 file for the test driver, otherwise specified by ``--harness-dir``. 4524 4525 * ``Additional_Tests`` 4526 is used to specify the project file, otherwise given by 4527 ``--additional-tests`` switch. 4528 4529 * ``Skeletons_Default`` 4530 is used to specify the default behavior of test skeletons, otherwise 4531 specified by ``--skeleton-default`` option. The value of this attribute 4532 should be either ``pass`` or ``fail``. 4533 4534 Each of those attributes can be overridden from the command line if needed. 4535 Other *gnattest* switches can also be passed via the project 4536 file as an attribute list called *Gnattest_Switches*. 4537 4538 4539 .. _Simple_gnattest_Example: 4540 4541 Simple Example 4542 -------------- 4543 4544 Let's take a very simple example using the first *gnattest* example 4545 located in: 4546 4547 :: 4548 4549 <install_prefix>/share/examples/gnattest/simple 4550 4551 This project contains a simple package containing one subprogram. By running *gnattest*: 4552 4553 :: 4554 4555 $ gnattest --harness-dir=driver -Psimple.gpr 4556 4557 a test driver is created in directory ``driver``. It can be compiled and run: 4558 4559 :: 4560 4561 $ cd obj/driver 4562 $ gnatmake -Ptest_driver 4563 $ test_runner 4564 4565 One failed test with the diagnosis "test not implemented" is reported. 4566 Since no special output option was specified, the test package ``Simple.Tests`` 4567 is located in: 4568 4569 :: 4570 4571 <install_prefix>/share/examples/gnattest/simple/obj/gnattest/tests 4572 4573 4574 For each package containing visible subprograms, a child test package is 4575 generated. It contains one test routine per tested subprogram. Each 4576 declaration of a test subprogram has a comment specifying which tested 4577 subprogram it corresponds to. Bodies of test routines are placed in test package 4578 bodies and are surrounded by special comment sections. Those comment sections 4579 should not be removed or modified in order for gnattest to be able to regenerate 4580 test packages and keep already written tests in place. 4581 The test routine `Test_Inc_5eaee3` located at ``simple-test_data-tests.adb`` contains 4582 a single statement: a call to procedure `Assert`. It has two arguments: 4583 the Boolean expression we want to check and the diagnosis message to display if 4584 the condition is false. 4585 4586 That is where actual testing code should be written after a proper setup. 4587 An actual check can be performed by replacing the `Assert` call with: 4588 4589 :: 4590 4591 Assert (Inc (1) = 2, "wrong incrementation"); 4592 4593 After recompiling and running the test driver, one successfully passed test 4594 is reported. 4595 4596 4597 .. _Setting_Up_and_Tearing_Down_the_Testing_Environment: 4598 4599 Setting Up and Tearing Down the Testing Environment 4600 --------------------------------------------------- 4601 4602 Besides test routines themselves, each test package has a parent package 4603 `Test_Data` that has two procedures: `Set_Up` and `Tear_Down`. This package is never 4604 overwritten by the tool. `Set_Up` is called before each test routine of the 4605 package, and `Tear_Down` is called after each test routine. Those two procedures 4606 can be used to perform necessary initialization and finalization, 4607 memory allocation, etc. Test type declared in `Test_Data` package is parent type 4608 for the test type of test package and can have user-defined components whose 4609 values can be set by `Set_Up` routine and used in test routines afterwards. 4610 4611 4612 .. _Regenerating_Tests: 4613 4614 Regenerating Tests 4615 ------------------ 4616 4617 Bodies of test routines and `Test_Data` packages are never overridden after they 4618 have been created once. As long as the name of the subprogram, full expanded Ada 4619 names and order of its parameters are the same, and comment sections are 4620 intact, the old test routine will fit in its place and no test skeleton will be 4621 generated for the subprogram. 4622 4623 This can be demonstrated with the previous example. By uncommenting declaration 4624 and body of function Dec in ``simple.ads`` and ``simple.adb``, running 4625 *gnattest* on the project, and then running the test driver: 4626 4627 :: 4628 4629 $ gnattest --harness-dir=driver -Psimple.gpr 4630 $ cd obj/driver 4631 $ gprbuild -Ptest_driver 4632 $ test_runner 4633 4634 The old test is not replaced with a stub, nor is it lost, but a new test 4635 skeleton is created for function `Dec`. 4636 4637 The only way of regenerating tests skeletons is to remove the previously created 4638 tests together with corresponding comment sections. 4639 4640 4641 .. _Default_Test_Behavior: 4642 4643 Default Test Behavior 4644 --------------------- 4645 4646 The generated test driver can treat unimplemented tests in two ways: 4647 either count them all as failed (this is useful to see which tests are still 4648 left to implement) or as passed (to sort out unimplemented ones from those 4649 actually failing). 4650 4651 The test driver accepts a switch to specify this behavior: 4652 :samp:`--skeleton-default={val}`, where ``val`` is either ``pass`` or ``fail`` (exactly as for 4653 *gnattest*). 4654 4655 The default behavior of the test driver is set with the same switch 4656 as passed to *gnattest* when generating the test driver. 4657 4658 Passing it to the driver generated on the first example: 4659 4660 :: 4661 4662 $ test_runner --skeleton-default=pass 4663 4664 makes both tests pass, even the unimplemented one. 4665 4666 4667 .. _Testing_Primitive_Operations_of_Tagged_Types: 4668 4669 Testing Primitive Operations of Tagged Types 4670 -------------------------------------------- 4671 4672 Creation of test skeletons for primitive operations of tagged types entails 4673 a number of features. Test routines for all primitives of a given tagged type 4674 are placed in a separate child package named according to the tagged type. For 4675 example, if you have tagged type *T* in package *P*, all tests for primitives 4676 of *T* will be in *P.T_Test_Data.T_Tests*. 4677 4678 Consider running *gnattest* on the second example (note: actual tests for this 4679 example already exist, so there's no need to worry if the tool reports that 4680 no new stubs were generated): 4681 4682 :: 4683 4684 $ cd <install_prefix>/share/examples/gnattest/tagged_rec 4685 $ gnattest --harness-dir=driver -Ptagged_rec.gpr 4686 4687 Taking a closer look at the test type declared in the test package 4688 *Speed1.Controller_Test_Data* is necessary. It is declared in: 4689 4690 :: 4691 4692 <install_prefix>/share/examples/gnattest/tagged_rec/obj/gnattest/tests 4693 4694 Test types are direct or indirect descendants of 4695 *AUnit.Test_Fixtures.Test_Fixture* type. In the case of non-primitive tested 4696 subprograms, the user doesn't need to be concerned with them. However, 4697 when generating test packages for primitive operations, there are some things 4698 the user needs to know. 4699 4700 Type *Test_Controller* has components that allow assignment of various 4701 derivations of type *Controller*. And if you look at the specification of 4702 package *Speed2.Auto_Controller*, you will see that *Test_Auto_Controller* 4703 actually derives from *Test_Controller* rather than AUnit type *Test_Fixture*. 4704 Thus, test types mirror the hierarchy of tested types. 4705 4706 The *Set_Up* procedure of *Test_Data* package corresponding to a test package 4707 of primitive operations of type *T* assigns to *Fixture* a reference to an 4708 object of that exact type *T*. Note, however, that if the tagged type has 4709 discriminants, the *Set_Up* only has a commented template for setting 4710 up the fixture, since filling the discriminant with actual value is up 4711 to the user. 4712 4713 The knowledge of the structure of test types allows additional testing 4714 without additional effort. Those possibilities are described below. 4715 4716 4717 .. _Testing_Inheritance: 4718 4719 Testing Inheritance 4720 ------------------- 4721 4722 Since the test type hierarchy mimics the hierarchy of tested types, the 4723 inheritance of tests takes place. An example of such inheritance can be 4724 seen by running the test driver generated for the second example. As previously 4725 mentioned, actual tests are already written for this example. 4726 4727 :: 4728 4729 $ cd obj/driver 4730 $ gprbuild -Ptest_driver 4731 $ test_runner 4732 4733 There are 6 passed tests while there are only 5 testable subprograms. The test 4734 routine for function Speed has been inherited and run against objects of the 4735 derived type. 4736 4737 4738 .. _Tagged_Type_Substitutability_Testing: 4739 4740 Tagged Type Substitutability Testing 4741 ------------------------------------ 4742 4743 *Tagged Type Substitutability Testing* is a way of verifying the global type 4744 consistency by testing. Global type consistency is a principle stating that if 4745 *S* is a subtype of *T* (in Ada, *S* is a derived type of tagged type *T*), 4746 then objects of type *T* may be replaced with objects of type *S* (that is, 4747 objects of type *S* may be substituted for objects of type *T*), without 4748 altering any of the desirable properties of the program. When the properties 4749 of the program are expressed in the form of subprogram preconditions and 4750 postconditions (let's call them pre and post), the principle is formulated as 4751 relations between the pre and post of primitive operations and the pre and post 4752 of their derived operations. The pre of a derived operation should not be 4753 stronger than the original pre, and the post of the derived operation should 4754 not be weaker than the original post. Those relations ensure that verifying if 4755 a dispatching call is safe can be done just by using the pre and post of the 4756 root operation. 4757 4758 Verifying global type consistency by testing consists of running all the unit 4759 tests associated with the primitives of a given tagged type with objects of its 4760 derived types. 4761 4762 In the example used in the previous section, there was clearly a violation of 4763 type consistency. The overriding primitive *Adjust_Speed* in package *Speed2* 4764 removes the functionality of the overridden primitive and thus doesn't respect 4765 the consistency principle. 4766 *Gnattest* has a special option to run overridden parent tests against objects 4767 of the type which have overriding primitives: 4768 4769 :: 4770 4771 $ gnattest --harness-dir=driver --validate-type-extensions -Ptagged_rec.gpr 4772 $ cd obj/driver 4773 $ gprbuild -Ptest_driver 4774 $ test_runner 4775 4776 While all the tests pass by themselves, the parent test for *Adjust_Speed* fails 4777 against objects of the derived type. 4778 4779 Non-overridden tests are already inherited for derived test types, so the 4780 ``--validate-type-extensions`` enables the application of overridden tests 4781 to objects of derived types. 4782 4783 4784 .. _Testing_with_Contracts: 4785 4786 Testing with Contracts 4787 ---------------------- 4788 4789 *gnattest* supports pragmas *Precondition*, *Postcondition*, and *Test_Case*, 4790 as well as the corresponding Ada 2012 aspects. 4791 Test routines are generated, one per each *Test_Case* associated with a tested 4792 subprogram. Those test routines have special wrappers for tested functions 4793 that have composition of pre- and postcondition of the subprogram with 4794 "requires" and "ensures" of the *Test_Case* (depending on the mode, pre and post 4795 either count for *Nominal* mode or do **not** count for *Robustness* mode). 4796 4797 The third example demonstrates how this works: 4798 4799 :: 4800 4801 $ cd <install_prefix>/share/examples/gnattest/contracts 4802 $ gnattest --harness-dir=driver -Pcontracts.gpr 4803 4804 Putting actual checks within the range of the contract does not cause any 4805 error reports. For example, for the test routine which corresponds to 4806 test case 1: 4807 4808 :: 4809 4810 Assert (Sqrt (9.0) = 3.0, "wrong sqrt"); 4811 4812 and for the test routine corresponding to test case 2: 4813 4814 :: 4815 4816 Assert (Sqrt (-5.0) = -1.0, "wrong error indication"); 4817 4818 are acceptable: 4819 4820 :: 4821 4822 $ cd obj/driver 4823 $ gprbuild -Ptest_driver 4824 $ test_runner 4825 4826 However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get 4827 a precondition violation for test case one. Also, by using any otherwise 4828 correct but positive pair of numbers in the second test routine, you can also 4829 get a precondition violation. Postconditions are checked and reported 4830 the same way. 4831 4832 4833 .. _Additional_Tests: 4834 4835 Additional Tests 4836 ---------------- 4837 4838 *gnattest* can add user-written tests to the main suite of the test 4839 driver. *gnattest* traverses the given packages and searches for test 4840 routines. All procedures with a single in out parameter of a type which is 4841 derived from *AUnit.Test_Fixtures.Test_Fixture* and that are declared in package 4842 specifications are added to the suites and are then executed by the test driver. 4843 (*Set_Up* and *Tear_Down* are filtered out.) 4844 4845 An example illustrates two ways of creating test harnesses for user-written 4846 tests. Directory `additional_tests` contains an AUnit-based test driver written 4847 by hand. 4848 4849 :: 4850 4851 <install_prefix>/share/examples/gnattest/additional_tests/ 4852 4853 To create a test driver for already-written tests, use the ``--harness-only`` 4854 option: 4855 4856 :: 4857 4858 gnattest -Padditional/harness/harness.gpr --harness-dir=harness_only \\ 4859 --harness-only 4860 gprbuild -Pharness_only/test_driver.gpr 4861 harness_only/test_runner 4862 4863 Additional tests can also be executed together with generated tests: 4864 4865 :: 4866 4867 gnattest -Psimple.gpr --additional-tests=additional/harness/harness.gpr \\ 4868 --harness-dir=mixing 4869 gprbuild -Pmixing/test_driver.gpr 4870 mixing/test_runner 4871 4872 4873 .. _Individual_Test_Drivers: 4874 4875 Individual Test Drivers 4876 ----------------------- 4877 4878 By default, *gnattest* generates a monolithic test driver that 4879 aggregates the individual tests into a single executable. It is also possible 4880 to generate separate executables for each test, by passing the switch 4881 ``--separate-drivers``. This approach scales better for large testing 4882 campaigns, especially involving target architectures with limited resources 4883 typical for embedded development. It can also provide a major performance 4884 benefit on multi-core systems by allowing simultaneous execution of multiple 4885 tests. 4886 4887 *gnattest* can take charge of executing the individual tests; for this, 4888 instead of passing a project file, a text file containing the list of 4889 executables can be passed. Such a file is automatically generated by gnattest 4890 under the name :file:`test_drivers.list`, but it can be 4891 hand-edited to add or remove tests, or replaced. The individual tests can 4892 also be executed standalone, or from any user-defined scripted framework. 4893 4894 4895 .. _Stubbing: 4896 4897 Stubbing 4898 -------- 4899 4900 Depending on the testing campaign, it is sometimes necessary to isolate the 4901 part of the algorithm under test from its dependencies. This is accomplished 4902 via *stubbing*, i.e. replacing the subprograms that are called from the 4903 subprogram under test by stand-in subprograms that match the profiles of the 4904 original ones, but simply return predetermined values required by the test 4905 scenario. 4906 4907 This mode of test harness generation is activated by the switch ``--stub``. 4908 4909 The implementation approach chosen by *gnattest* is as follows. 4910 For each package under consideration all the packages it is directly depending 4911 on are stubbed, excluding the generic packages and package instantiations. 4912 The stubs are shared for each package under test. The specs of packages to stub 4913 remain intact, while their bodies are replaced, and hide the original bodies by 4914 means of extending projects. Also, for each stubbed 4915 package, a child package with setter routines for each subprogram declaration 4916 is created. These setters are meant to be used to set the behavior of 4917 stubbed subprograms from within test cases. 4918 4919 Note that subprograms belonging to the same package as the subprogram under 4920 test are not stubbed. This guarantees that the sources being tested are 4921 exactly the sources used for production, which is an important property for 4922 establishing the traceability between the testing campaign and production code. 4923 4924 Due to the nature of stubbing process, this mode implies the switch 4925 ``--separate-drivers``, i.e. an individual test driver (with the 4926 corresponding hierarchy of extending projects) is generated for each test. 4927 4928 .. note:: 4929 4930 Developing a stubs-based testing campaign requires 4931 good understanding of the infrastructure created by *gnattest* for 4932 this purpose. We recommend following the two stubbing tutorials 4933 `simple_stubbing` and `advanced_stubbing` provided 4934 under :file:`<install_prefix>/share/examples/gnattest` before 4935 attempting to use this powerful feature. 4936 4937 4938 .. _Putting_Tests_under_Version_Control: 4939 4940 Putting Tests under Version Control 4941 ----------------------------------- 4942 4943 As has been stated earlier, *gnattest* generates two different types 4944 of code, test skeletons and harness. The harness is generated completely 4945 automatically each time, does not require manual changes and therefore should 4946 not be put under version control. 4947 It makes sense to put under version control files containing test data packages, 4948 both specs and bodies, and files containing bodies of test packages. Note that 4949 test package specs are also generated automatically each time and should not be 4950 put under version control. 4951 Option ``--omit-sloc`` may be useful when putting test packages under version control. 4952 4953 4954 .. _Current_Limitations: 4955 4956 Current Limitations 4957 ------------------- 4958 4959 The tool currently has the following limitations: 4960 4961 * generic tests for nested generic packages and their instantiations are 4962 not supported; 4963 * tests for protected subprograms and entries are not supported; 4964 * pragma *No_Run_Time* is not supported; 4965 * if pragmas for interfacing with foreign languages are used, manual 4966 adjustments might be necessary to make the test harness compilable; 4967 * use of elaboration control pragmas may result in elaboration circularities 4968 in the generated harness. 4969