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