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. 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 a 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 reported. 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 The ``gnatmetric`` command has the form 1812 1813 :: 1814 1815 $ gnatmetric [ switches ] { filename } 1816 1817 where: 1818 1819 * ``switches`` specify the metrics to compute and define the destination for 1820 the output 1821 1822 * Each ``filename`` is the name of a source file to process. 'Wildcards' are 1823 allowed, and the file name may contain path information. If no 1824 ``filename`` is supplied, then the ``switches`` list must contain at least 1825 one :switch:`--files` switch (see :ref:`Other_gnatmetric_Switches`). 1826 Including both a :switch:`--files` switch and one or more ``filename`` 1827 arguments is permitted. 1828 1829 Note that it is no longer necessary to specify the Ada language version; 1830 ``gnatmetric`` can process Ada source code written in any version from 1831 Ada 83 onward without specifying any language version switch. 1832 1833 The following subsections describe the various switches accepted by 1834 ``gnatmetric``, organized by category. 1835 1836 .. _Output_File_Control-gnatmetric: 1837 1838 Output File Control 1839 ------------------- 1840 1841 .. index:: Output file control in gnatmetric 1842 1843 ``gnatmetric`` has two output formats. It can generate a 1844 textual (human-readable) form, and also XML. By default only textual 1845 output is generated. 1846 1847 When generating the output in textual form, ``gnatmetric`` creates 1848 for each Ada source file a corresponding text file 1849 containing the computed metrics, except for the case when the set of metrics 1850 specified by gnatmetric parameters consists only of metrics that are computed 1851 for the whole set of analyzed sources, but not for each Ada source. 1852 By default, the name of the file containing metric information for a source 1853 is obtained by appending the :file:`.metrix` suffix to the 1854 name of the input source file. If not otherwise specified and no project file 1855 is specified as ``gnatmetric`` option this file is placed in the same 1856 directory as where the source file is located. If ``gnatmetric`` has a 1857 project file as its parameter, it places all the generated files in the 1858 object directory of the project (or in the project source directory if the 1859 project does not define an object directory). If :switch:`--subdirs` option 1860 is specified, the files are placed in the subrirectory of this directory 1861 specified by this option. 1862 1863 All the output information generated in XML format is placed in a single 1864 file. By default the name of this file is :file:`metrix.xml`. 1865 If not otherwise specified and if no project file is specified 1866 as ``gnatmetric`` option this file is placed in the 1867 current directory. 1868 1869 Some of the computed metrics are summed over the units passed to 1870 ``gnatmetric``; for example, the total number of lines of code. 1871 By default this information is sent to :file:`stdout`, but a file 1872 can be specified with the :switch:`--global-file-name` switch. 1873 1874 The following switches control the ``gnatmetric`` output: 1875 1876 .. index:: --generate-xml-output (gnatmetric) 1877 1878 :switch:`--generate-xml-output` 1879 Generate XML output. 1880 1881 .. index:: --generate-xml-schema (gnatmetric) 1882 1883 :switch:`--generate-xml-schema` 1884 Generate XML output and an XML schema file that describes the structure 1885 of the XML metric report. This schema is assigned to the XML file. The schema 1886 file has the same name as the XML output file with :file:`.xml` suffix replaced 1887 with :file:`.xsd`. 1888 1889 .. index:: --no-text-output (gnatmetric) 1890 1891 1892 :switch:`--no-text-output` 1893 Do not generate the output in text form (implies :switch:`-x`). 1894 1895 .. index:: --output-dir (gnatmetric) 1896 1897 1898 :switch:`--output-dir={output_dir}` 1899 Put text files with detailed metrics into ``output_dir``. 1900 1901 .. index:: --output-suffix (gnatmetric) 1902 1903 1904 :switch:`--output-suffix={file_suffix}` 1905 Use ``file_suffix``, instead of :file:`.metrix` 1906 in the name of the output file. 1907 1908 .. index:: --global-file-name (gnatmetric) 1909 1910 :switch:`--global-file-name={file_name}` 1911 Put global metrics into ``file_name``. 1912 1913 .. index:: --xml-file-name (gnatmetric) 1914 1915 1916 :switch:`--xml-file-name={file_name}` 1917 Put the XML output into ``file_name`` 1918 (also implies :switch:`--generate-xml-output`). 1919 1920 .. index:: --short-file-names (gnatmetric) 1921 1922 :switch:`--short-file-names` 1923 Use 'short' source file names in the output. (The ``gnatmetric`` 1924 output includes the name(s) of the Ada source file(s) from which the 1925 metrics are computed. By default each name includes the absolute 1926 path. The :switch:`--short-file-names` switch causes ``gnatmetric`` 1927 to exclude all directory information from the file names that are 1928 output.) 1929 1930 .. index:: --wide-character-encoding (gnatmetric) 1931 1932 :switch:`--wide-character-encoding={e}` 1933 Specify the wide character encoding method for the input and output 1934 files. ``e`` is one of the following: 1935 1936 * *8* - UTF-8 encoding 1937 1938 * *b* - Brackets encoding (default value) 1939 1940 1941 .. index:: Disable Metrics For Local Units in gnatmetric 1942 1943 .. _Disable_Metrics_For_Local_Units: 1944 1945 Disable Metrics For Local Units 1946 ------------------------------- 1947 1948 ``gnatmetric`` relies on the GNAT compilation model -- 1949 one compilation 1950 unit per one source file. It computes line metrics for the whole source 1951 file, and it also computes syntax 1952 and complexity metrics for the file's outermost unit. 1953 1954 By default, ``gnatmetric`` will also compute all metrics for certain 1955 kinds of locally declared program units: 1956 1957 * subprogram (and generic subprogram) bodies; 1958 1959 * package (and generic package) specs and bodies; 1960 1961 * task object and type specifications and bodies; 1962 1963 * protected object and type specifications and bodies. 1964 1965 .. index:: Eligible local unit (for gnatmetric) 1966 1967 These kinds of entities will be referred to as 1968 *eligible local program units*, or simply *eligible local units*, 1969 in the discussion below. 1970 1971 Note that a subprogram declaration, generic instantiation, 1972 or renaming declaration only receives metrics 1973 computation when it appear as the outermost entity 1974 in a source file. 1975 1976 Suppression of metrics computation for eligible local units can be 1977 obtained via the following switch: 1978 1979 1980 .. index:: --no-local-metrics (gnatmetric) 1981 1982 1983 :switch:`--no-local-metrics` 1984 Do not compute detailed metrics for eligible local program units. 1985 1986 1987 .. _Specifying_a_set_of_metrics_to_compute: 1988 1989 Specifying a set of metrics to compute 1990 -------------------------------------- 1991 1992 By default all the metrics are reported. The switches described in this 1993 subsection allow you to control, on an individual basis, whether metrics are 1994 reported. If at least one positive metric switch is specified (that is, a 1995 switch that defines that a given metric or set of metrics is to be computed), 1996 then only explicitly specified metrics are reported. 1997 1998 .. _Line_Metrics_Control: 1999 2000 Line Metrics Control 2001 ^^^^^^^^^^^^^^^^^^^^ 2002 2003 .. index:: Line metrics control in gnatmetric 2004 2005 For each source file, and for each of its eligible local program 2006 units, ``gnatmetric`` computes the following metrics: 2007 2008 * the total number of lines; 2009 2010 * the total number of code lines (i.e., non-blank lines that are not 2011 comments) 2012 2013 * the number of comment lines 2014 2015 * the number of code lines containing end-of-line comments; 2016 2017 * the comment percentage: the ratio between the number of lines that 2018 contain comments and the number of all non-blank lines, expressed as 2019 a percentage 2020 2021 * the number of empty lines and lines containing only space characters 2022 and/or format effectors (blank lines) 2023 2024 * the average number of code lines in subprogram bodies, task bodies, 2025 entry bodies and statement sequences in package bodies 2026 2027 ``gnatmetric`` sums the values of the line metrics for all the files 2028 being processed and then generates the cumulative results. The tool 2029 also computes for all the files being processed the average number of 2030 code lines in bodies. 2031 2032 You can use the following switches to select the specific line metrics 2033 to be reported. 2034 2035 2036 .. index:: --lines (gnatmetric) 2037 .. index:: --no-lines (gnatmetric) 2038 2039 2040 :switch:`--lines-all` 2041 Report all the line metrics 2042 2043 2044 :switch:`--no-lines-all` 2045 Do not report any of line metrics 2046 2047 2048 :switch:`--lines` 2049 Report the number of all lines 2050 2051 2052 :switch:`--no-lines` 2053 Do not report the number of all lines 2054 2055 2056 :switch:`--lines-code` 2057 Report the number of code lines 2058 2059 2060 :switch:`--no-lines-code` 2061 Do not report the number of code lines 2062 2063 2064 :switch:`--lines-comment` 2065 Report the number of comment lines 2066 2067 2068 :switch:`--no-lines-comment` 2069 Do not report the number of comment lines 2070 2071 2072 :switch:`--lines-eol-comment` 2073 Report the number of code lines containing 2074 end-of-line comments 2075 2076 2077 :switch:`--no-lines-eol-comment` 2078 Do not report the number of code lines containing 2079 end-of-line comments 2080 2081 2082 :switch:`--lines-ratio` 2083 Report the comment percentage in the program text 2084 2085 2086 :switch:`--no-lines-ratio` 2087 Do not report the comment percentage in the program text 2088 2089 2090 :switch:`--lines-blank` 2091 Report the number of blank lines 2092 2093 2094 :switch:`--no-lines-blank` 2095 Do not report the number of blank lines 2096 2097 2098 :switch:`--lines-average` 2099 Report the average number of code lines in subprogram bodies, task bodies, 2100 entry bodies and statement sequences in package bodies. 2101 2102 2103 :switch:`--no-lines-average` 2104 Do not report the average number of code lines in subprogram bodies, 2105 task bodies, entry bodies and statement sequences in package bodies. 2106 2107 2108 :switch:`--lines-spark` 2109 Report the number of lines written in SPARK. 2110 2111 2112 :switch:`--no-lines-spark` 2113 Do not report the number of lines written in SPARK. 2114 2115 2116 .. _Syntax_Metrics_Control: 2117 2118 Syntax Metrics Control 2119 ^^^^^^^^^^^^^^^^^^^^^^ 2120 2121 .. index:: Syntax metrics control in gnatmetric 2122 2123 ``gnatmetric`` computes various syntactic metrics for the 2124 outermost unit and for each eligible local unit: 2125 2126 * *LSLOC ('Logical Source Lines Of Code')* 2127 The total number of declarations and the total number of 2128 statements. Note that the definition of declarations is the one 2129 given in the reference manual: 2130 2131 "Each of the following is defined to be a declaration: any 2132 basic_declaration; an enumeration_literal_specification; a 2133 discriminant_specification; a component_declaration; a 2134 loop_parameter_specification; a parameter_specification; a 2135 subprogram_body; an entry_declaration; an 2136 entry_index_specification; a choice_parameter_specification; a 2137 generic_formal_parameter_declaration." 2138 2139 This means for example that each enumeration literal adds one to 2140 the count, as well as each subprogram parameter. 2141 2142 * *Maximal static nesting level of inner program units* 2143 According to :title:`Ada Reference Manual`, 10.1(1): 2144 2145 "A program unit is either a package, a task unit, a protected 2146 unit, a protected entry, a generic unit, or an explicitly 2147 declared subprogram other than an enumeration literal." 2148 2149 * *Maximal nesting level of composite syntactic constructs* 2150 This corresponds to the notion of the maximum nesting level in the 2151 GNAT built-in style checks (see :ref:`Style_Checking`). 2152 2153 * *Number of formal parameters* 2154 Number of formal parameters of a subprogram; if a subprogram does 2155 have parameters, then numbers of "in", "out" and "in out" 2156 parameters are also reported. This metric is reported for 2157 subprogram specifications and for subprogram instantiations. For 2158 subprogram bodies, expression functions and null procedures this 2159 metric is reported if the construct acts as a subprogram 2160 declaration but is not a completion of previous declaration. This 2161 metric is not reported for generic and formal subprograms. 2162 2163 For the outermost unit in the file, ``gnatmetric`` additionally 2164 computes the following metrics: 2165 2166 * *Public subprograms* 2167 This metric is computed for package specs. It is the number of 2168 subprograms and generic subprograms declared in the visible part 2169 (including the visible part of nested packages, protected objects, 2170 and protected types). 2171 2172 2173 * *All subprograms* 2174 This metric is computed for bodies and subunits. The metric is 2175 equal to a total number of subprogram bodies in the compilation 2176 unit. 2177 Neither generic instantiations nor renamings-as-a-body nor body 2178 stubs are counted. Any subprogram body is counted, independently 2179 of its nesting level and enclosing constructs. Generic bodies and 2180 bodies of protected subprograms are counted in the same way as 2181 'usual' subprogram bodies. 2182 2183 2184 * *Public types* 2185 This metric is computed for package specs and generic package 2186 declarations. It is the total number of types that can be 2187 referenced from outside this compilation unit, plus the number of 2188 types from all the visible parts of all the visible generic 2189 packages. Generic formal types are not counted. Only types, not 2190 subtypes, are included. 2191 2192 Along with the total number of public types, the following 2193 types are counted and reported separately: 2194 2195 * *Abstract types* 2196 2197 * *Root tagged types^ (abstract, non-abstract, private, 2198 non-private). Type extensions are *not* counted 2199 2200 * *Private types* (including private extensions) 2201 2202 * *Task types* 2203 2204 * *Protected types* 2205 2206 * *All types* 2207 This metric is computed for any compilation unit. It is equal to 2208 the total number of the declarations of different types given in 2209 the compilation unit. The private and the corresponding full type 2210 declaration are counted as one type declaration. Incomplete type 2211 declarations and generic formal types are not counted. 2212 No distinction is made among different kinds of types (abstract, 2213 private etc.); the total number of types is reported. 2214 2215 By default, all the syntax metrics are reported. You can use the following 2216 switches to select specific syntax metrics. 2217 2218 2219 .. index:: --syntax (gnatmetric) 2220 .. index:: --no-syntax (gnatmetric) 2221 2222 2223 :switch:`--syntax-all` 2224 Report all the syntax metrics 2225 2226 2227 :switch:`--no-syntax-all` 2228 Do not report any of syntax metrics 2229 2230 2231 :switch:`--declarations` 2232 Report the total number of declarations 2233 2234 2235 :switch:`--no-declarations` 2236 Do not report the total number of declarations 2237 2238 2239 :switch:`--statements` 2240 Report the total number of statements 2241 2242 2243 :switch:`--no-statements` 2244 Do not report the total number of statements 2245 2246 2247 :switch:`--public-subprograms` 2248 Report the number of public subprograms in a compilation unit 2249 2250 2251 :switch:`--no-public-subprograms` 2252 Do not report the number of public subprograms in a compilation unit 2253 2254 2255 :switch:`--all-subprograms` 2256 Report the number of all the subprograms in a compilation unit 2257 2258 2259 :switch:`--no-all-subprograms` 2260 Do not report the number of all the subprograms in a compilation unit 2261 2262 2263 :switch:`--public-types` 2264 Report the number of public types in a compilation unit 2265 2266 2267 :switch:`--no-public-types` 2268 Do not report the number of public types in a compilation unit 2269 2270 2271 :switch:`--all-types` 2272 Report the number of all the types in a compilation unit 2273 2274 2275 :switch:`--no-all-types` 2276 Do not report the number of all the types in a compilation unit 2277 2278 2279 :switch:`--unit-nesting` 2280 Report the maximal program unit nesting level 2281 2282 2283 :switch:`--no-unit-nesting` 2284 Do not report the maximal program unit nesting level 2285 2286 2287 :switch:`--construct-nesting` 2288 Report the maximal construct nesting level 2289 2290 2291 :switch:`--no-construct-nesting` 2292 Do not report the maximal construct nesting level 2293 2294 :switch:`--param-number` 2295 Report the number of subprogram parameters 2296 2297 2298 :switch:`--no-param-number` 2299 Do not report the number of subprogram parameters 2300 2301 2302 .. _Contract_Metrics_Control: 2303 2304 Contract Metrics Control 2305 ^^^^^^^^^^^^^^^^^^^^^^^^ 2306 2307 .. index:: Contract metrics control in gnatmetric 2308 2309 :switch:`--contract-all` 2310 Report all the contract metrics 2311 2312 2313 :switch:`--no-contract-all` 2314 Do not report any of the contract metrics 2315 2316 2317 :switch:`--contract` 2318 Report the number of public subprograms with contracts 2319 2320 2321 :switch:`--no-contract` 2322 Do not report the number of public subprograms with contracts 2323 2324 2325 :switch:`--post` 2326 Report the number of public subprograms with postconditions 2327 2328 2329 :switch:`--no-post` 2330 Do not report the number of public subprograms with postconditions 2331 2332 2333 :switch:`--contract-complete` 2334 Report the number of public subprograms with complete contracts 2335 2336 2337 :switch:`--no-contract-complete` 2338 Do not report the number of public subprograms with complete contracts 2339 2340 2341 :switch:`--contract-all` 2342 Report the McCabe complexity of public subprograms 2343 2344 2345 :switch:`--no-contract-all` 2346 Do not report the McCabe complexity of public subprograms 2347 2348 2349 .. _Complexity_Metrics_Control: 2350 2351 Complexity Metrics Control 2352 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 2353 2354 .. index:: Complexity metrics control in gnatmetric 2355 2356 For a program unit that is an executable body (a subprogram body 2357 (including generic bodies), task body, entry body or a package body 2358 containing its own statement sequence) ``gnatmetric`` computes the 2359 following complexity metrics: 2360 2361 * McCabe cyclomatic complexity; 2362 2363 * McCabe essential complexity; 2364 2365 * maximal loop nesting level; 2366 2367 * extra exit points (for subprograms); 2368 2369 The McCabe cyclomatic complexity metric is defined 2370 in `http://www.mccabe.com/pdf/mccabe-nist235r.pdf <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_ 2371 2372 According to McCabe, both control statements and short-circuit control 2373 forms should be taken into account when computing cyclomatic 2374 complexity. For Ada 2012 we have also take into account conditional 2375 expressions and quantified expressions. For each body, we compute 2376 three metric values: 2377 2378 * the complexity introduced by control 2379 statements only, without taking into account short-circuit forms 2380 (referred as ``statement complexity`` in ``gnatmetric`` output), 2381 2382 * the complexity introduced by short-circuit control forms only 2383 (referred as ``expression complexity`` in ``gnatmetric`` output), 2384 and 2385 2386 * the total 2387 cyclomatic complexity, which is the sum of these two values 2388 (referred as ``cyclomatic complexity`` in ``gnatmetric`` output). 2389 2390 The cyclomatic complexity is also computed for Ada 2012 expression functions. 2391 An expression function cannot have statements as its components, so only one 2392 metric value is computed as a cyclomatic complexity of an expression function. 2393 2394 The origin of cyclomatic complexity metric is the need to estimate the number 2395 of independent paths in the control flow graph that in turn gives the number 2396 of tests needed to satisfy paths coverage testing completeness criterion. 2397 Considered from the testing point of view, a static Ada ``loop`` (that is, 2398 the ``loop`` statement having static subtype in loop parameter 2399 specification) does not add to cyclomatic complexity. By providing 2400 :switch:`--no-static-loop` option a user 2401 may specify that such loops should not be counted when computing the 2402 cyclomatic complexity metric 2403 2404 The Ada essential complexity metric is a McCabe cyclomatic complexity metric 2405 counted for the code that is reduced by excluding all the pure structural Ada 2406 control statements. An compound statement is considered as a non-structural 2407 if it contains a ``raise`` or ``return`` statement as it subcomponent, 2408 or if it contains a ``goto`` statement that transfers the control outside 2409 the operator. A selective ``accept`` statement with a ``terminate`` alternative 2410 is considered a non-structural statement. When computing this metric, 2411 ``exit`` statements are treated in the same way as ``goto`` 2412 statements unless the :switch:`-ne` option is specified. 2413 2414 The Ada essential complexity metric defined here is intended to quantify 2415 the extent to which the software is unstructured. It is adapted from 2416 the McCabe essential complexity metric defined in 2417 http://www.mccabe.com/pdf/mccabe-nist235r.pdf 2418 but is modified to be more 2419 suitable for typical Ada usage. For example, short circuit forms 2420 are not penalized as unstructured in the Ada essential complexity metric. 2421 2422 When computing cyclomatic and essential complexity, ``gnatmetric`` skips 2423 the code in the exception handlers and in all the nested program units. The 2424 code of assertions and predicates (that is, subprogram preconditions and 2425 postconditions, subtype predicates and type invariants) is also skipped. 2426 2427 By default, all the complexity metrics are reported. For more fine-grained 2428 control you can use the following switches: 2429 2430 2431 .. index:: --complexity (gnatmetric) 2432 .. index:: --no-complexity (gnatmetric) 2433 2434 2435 :switch:`--complexity-all` 2436 Report all the complexity metrics 2437 2438 2439 :switch:`--no-complexity-all` 2440 Do not report any of the complexity metrics 2441 2442 2443 :switch:`--complexity-cyclomatic` 2444 Report the McCabe Cyclomatic Complexity 2445 2446 2447 :switch:`--no-complexity-cyclomatic` 2448 Do not report the McCabe Cyclomatic Complexity 2449 2450 2451 :switch:`--complexity-essential` 2452 Report the Essential Complexity 2453 2454 2455 :switch:`--no-complexity-essential` 2456 Do not report the Essential Complexity 2457 2458 2459 :switch:`--loop-nesting` 2460 Report maximal loop nesting level 2461 2462 2463 :switch:`-no-loop-nesting` 2464 Do not report maximal loop nesting level 2465 2466 2467 :switch:`--complexity-average` 2468 Report the average McCabe Cyclomatic Complexity for all the subprogram bodies, 2469 task bodies, entry bodies and statement sequences in package bodies. 2470 The metric is reported for whole set of processed Ada sources only. 2471 2472 2473 :switch:`--no-complexity-average` 2474 Do not report the average McCabe Cyclomatic Complexity for all the subprogram 2475 bodies, task bodies, entry bodies and statement sequences in package bodies 2476 2477 .. index:: --no-treat-exit-as-goto (gnatmetric) 2478 2479 2480 :switch:`--no-treat-exit-as-goto` 2481 Do not consider ``exit`` statements as ``goto``\ s when 2482 computing Essential Complexity 2483 2484 .. index:: --no-static-loop (gnatmetric) 2485 2486 2487 :switch:`--no-static-loop` 2488 Do not consider static loops when computing cyclomatic complexity 2489 2490 2491 :switch:`--extra-exit-points` 2492 Report the extra exit points for subprogram bodies. As an exit point, this 2493 metric counts ``return`` statements and raise statements in case when the 2494 raised exception is not handled in the same body. In case of a function this 2495 metric subtracts 1 from the number of exit points, because a function body 2496 must contain at least one ``return`` statement. 2497 2498 2499 :switch:`--no-extra-exit-points` 2500 Do not report the extra exit points for subprogram bodies 2501 2502 2503 .. _Coupling_Metrics_Control: 2504 2505 Coupling Metrics Control 2506 ^^^^^^^^^^^^^^^^^^^^^^^^ 2507 2508 .. index:: Coupling metrics control in gnatmetric 2509 2510 .. index:: Coupling metrics (in gnatmetric) 2511 2512 Coupling metrics measure the dependencies between a given entity and other 2513 entities in the program. This information is useful since high coupling 2514 may signal potential issues with maintainability as the program evolves. 2515 2516 ``gnatmetric`` computes the following coupling metrics: 2517 2518 2519 * *object-oriented coupling*, for classes in traditional object-oriented 2520 sense; 2521 2522 * *unit coupling*, for all the program units making up a program; 2523 2524 * *control coupling*, reflecting dependencies between a unit and 2525 other units that contain subprograms. 2526 2527 .. index:: fan-out coupling 2528 .. index:: efferent coupling 2529 2530 Two kinds of coupling metrics are computed: 2531 2532 * fan-out coupling ('efferent coupling'): 2533 the number of entities the given entity depends upon. This metric 2534 reflects how the given entity depends on the changes in the 2535 'external world'. 2536 2537 .. index:: fan-in coupling 2538 .. index:: afferent coupling 2539 2540 * fan-in coupling ('afferent' coupling): 2541 the number of entities that depend on a given entity. 2542 This metric reflects how the 'external world' depends on the changes in a 2543 given entity. 2544 2545 Object-oriented coupling metrics measure the dependencies 2546 between a given class (or a group of classes) and the other classes in the 2547 program. In this subsection the term 'class' is used in its traditional 2548 object-oriented programming sense (an instantiable module that contains data 2549 and/or method members). A *category* (of classes) is a group of closely 2550 related classes that are reused and/or modified together. 2551 2552 A class ``K``\ 's fan-out coupling is the number of classes 2553 that ``K`` depends upon. 2554 A category's fan-out coupling is the number of classes outside the 2555 category that the classes inside the category depend upon. 2556 2557 A class ``K``\ 's fan-in coupling is the number of classes 2558 that depend upon ``K``. 2559 A category's fan-in coupling is the number of classes outside the 2560 category that depend on classes belonging to the category. 2561 2562 Ada's object-oriented paradigm separates the instantiable entity 2563 (type) from the module (package), so the definition of the coupling 2564 metrics for Ada maps the class and class category notions 2565 onto Ada constructs. 2566 2567 For the coupling metrics, several kinds of modules that define a tagged type 2568 or an interface type -- library packages, library generic packages, and 2569 library generic package instantiations -- are considered to be classes. 2570 A category consists of a library package (or 2571 a library generic package) that defines a tagged or an interface type, 2572 together with all its descendant (generic) packages that define tagged 2573 or interface types. Thus a 2574 category is an Ada hierarchy of library-level program units. Class 2575 coupling in Ada is referred to as 'tagged coupling', and category coupling 2576 is referred to as 'hierarchy coupling'. 2577 2578 For any package serving as a class, its body and subunits (if any) are 2579 considered together with its spec when computing dependencies, and coupling 2580 metrics are reported for spec units only. Dependencies between classes 2581 mean Ada semantic dependencies. For object-oriented coupling 2582 metrics, only dependencies on units treated as classes are 2583 considered. 2584 2585 Similarly, for unit and control coupling an entity is considered to be the 2586 conceptual construct consisting of the entity's specification, body, and 2587 any subunits (transitively). 2588 ``gnatmetric`` computes 2589 the dependencies of all these units as a whole, but 2590 metrics are only reported for spec 2591 units (or for a subprogram body unit in case if there is no 2592 separate spec for the given subprogram). 2593 2594 For unit coupling, dependencies are computed between all kinds of program 2595 units. For control coupling, the dependencies of a given unit are limited to 2596 those units that define subprograms. Thus control fan-out coupling is reported 2597 for all units, but control fan-in coupling is only reported for units 2598 that define subprograms. 2599 2600 The following simple example illustrates the difference between unit coupling 2601 and control coupling metrics: 2602 2603 .. code-block:: ada 2604 2605 package Lib_1 is 2606 function F_1 (I : Integer) return Integer; 2607 end Lib_1; 2608 2609 package Lib_2 is 2610 type T_2 is new Integer; 2611 end Lib_2; 2612 2613 package body Lib_1 is 2614 function F_1 (I : Integer) return Integer is 2615 begin 2616 return I + 1; 2617 end F_1; 2618 end Lib_1; 2619 2620 with Lib_2; use Lib_2; 2621 package Pack is 2622 Var : T_2; 2623 function Fun (I : Integer) return Integer; 2624 end Pack; 2625 2626 with Lib_1; use Lib_1; 2627 package body Pack is 2628 function Fun (I : Integer) return Integer is 2629 begin 2630 return F_1 (I); 2631 end Fun; 2632 end Pack; 2633 2634 If we apply ``gnatmetric`` with the :switch:`--coupling-all` option to 2635 these units, the result will be: 2636 2637 :: 2638 2639 Coupling metrics: 2640 ================= 2641 Unit Lib_1 (C:\\customers\\662\\L406-007\\lib_1.ads) 2642 control fan-out coupling : 0 2643 control fan-in coupling : 1 2644 unit fan-out coupling : 0 2645 unit fan-in coupling : 1 2646 2647 Unit Pack (C:\\customers\\662\\L406-007\\pack.ads) 2648 control fan-out coupling : 1 2649 control fan-in coupling : 0 2650 unit fan-out coupling : 2 2651 unit fan-in coupling : 0 2652 2653 Unit Lib_2 (C:\\customers\\662\\L406-007\\lib_2.ads) 2654 control fan-out coupling : 0 2655 unit fan-out coupling : 0 2656 unit fan-in coupling : 1 2657 2658 The result does not contain values for object-oriented 2659 coupling because none of the argument units contains a tagged type and 2660 therefore none of these units can be treated as a class. 2661 2662 The ``Pack`` package (spec and body) depends on two 2663 units -- ``Lib_1`` and ``Lib_2`` -- and so its unit fan-out coupling 2664 is 2. Since nothing depends on it, its unit fan-in coupling is 0, as 2665 is its control fan-in coupling. Only one of the units ``Pack`` depends 2666 upon defines a subprogram, so its control fan-out coupling is 1. 2667 2668 ``Lib_2`` depends on nothing, so its fan-out metrics are 0. It does 2669 not define any subprograms, so it has no control fan-in metric. 2670 One unit (``Pack``) depends on it , so its unit fan-in coupling is 1. 2671 2672 ``Lib_1`` is similar to ``Lib_2``, but it does define a subprogram. 2673 Its control fan-in coupling is 1 (because there is one unit 2674 depending on it). 2675 2676 When computing coupling metrics, ``gnatmetric`` counts only 2677 dependencies between units that are arguments of the ``gnatmetric`` 2678 invocation. Coupling metrics are program-wide (or project-wide) metrics, so 2679 you should invoke ``gnatmetric`` for 2680 the complete set of sources comprising your program. This can be done 2681 by invoking ``gnatmetric`` with the corresponding project file 2682 and with the :switch:`-U` option. 2683 2684 By default, all the coupling metrics are reported. You can use the following 2685 switches to select specific syntax metrics. 2686 2687 .. index:: --tagged-coupling (gnatmetric) 2688 .. index:: --hierarchy-coupling (gnatmetric) 2689 .. index:: --unit-coupling (gnatmetric) 2690 .. index:: --control-coupling (gnatmetric) 2691 2692 :switch:`--coupling-all` 2693 Report all the coupling metrics 2694 2695 2696 :switch:`--tagged-coupling-out` 2697 Report tagged (class) fan-out coupling 2698 2699 2700 :switch:`--tagged-coupling-in` 2701 Report tagged (class) fan-in coupling 2702 2703 2704 :switch:`--hierarchy-coupling-out` 2705 Report hierarchy (category) fan-out coupling 2706 2707 2708 :switch:`--hierarchy-coupling-in` 2709 Report hierarchy (category) fan-in coupling 2710 2711 2712 :switch:`--unit-coupling-out` 2713 Report unit fan-out coupling 2714 2715 2716 :switch:`--unit-coupling-in` 2717 Report unit fan-in coupling 2718 2719 2720 :switch:`--control-coupling-out` 2721 Report control fan-out coupling 2722 2723 2724 :switch:`--control-coupling-in` 2725 Report control fan-in coupling 2726 2727 2728 .. _Other_gnatmetric_Switches: 2729 2730 Other ``gnatmetric`` Switches 2731 ----------------------------- 2732 2733 Additional ``gnatmetric`` switches are as follows: 2734 2735 2736 .. index:: --version (gnatmetric) 2737 2738 :switch:`--version` 2739 Display copyright and version, then exit disregarding all other options. 2740 2741 2742 .. index:: --help (gnatmetric) 2743 2744 :switch:`--help` 2745 Display usage, then exit disregarding all other options. 2746 2747 2748 .. index:: -P (gnatmetric) 2749 2750 :switch:`-P {file}` 2751 Indicates the name of the project file that describes the set of sources 2752 to be processed. The exact set of argument sources depends on other options 2753 specified, see below. An aggregate project is allowed as the file parameter 2754 only if it has exactly one non-aggregate project being aggregated. 2755 2756 2757 .. index:: -U (gnatmetric) 2758 2759 :switch:`-U` 2760 If a project file is specified and no argument source is explicitly 2761 specified (either directly or by means of :switch:`-files` option), process 2762 all the units of the closure of the argument project. Otherwise this option 2763 has no effect. 2764 2765 2766 :switch:`-U {main_unit}` 2767 If a project file is specified and no argument source is explicitly 2768 specified (either directly or by means of :switch:`-files` option), process 2769 the closure of units rooted at ``main_unit``. Otherwise this option 2770 has no effect. 2771 2772 2773 .. index:: -X (gnatmetric) 2774 2775 :switch:`-X{name}={value}` 2776 Indicates that external variable ``name`` in the argument project 2777 has the value ``value``. Has no effect if no project is specified. 2778 2779 2780 .. index:: --RTS (gnatmetric) 2781 2782 :switch:`--RTS={rts-path}` 2783 Specifies the default location of the runtime library. Same meaning as the 2784 equivalent ``gnatmake`` flag (see :ref:`Switches_for_gnatmake`). 2785 2786 2787 .. index:: --subdirs=dir (gnatmetric) 2788 2789 :switch:`--subdirs={dir}` 2790 Use the specified subdirectory of the project objects file (or of the 2791 project file directory if the project does not specify an object directory) 2792 for tool output files. Has no effect if no project is specified as 2793 tool argument r if :switch:`--no_objects_dir` is specified. 2794 2795 2796 .. index:: --files (gnatmetric) 2797 2798 :switch:`--files={file}` 2799 Take as arguments the files listed in text file ``file``. 2800 Text file ``file`` may contain empty lines that are ignored. 2801 Each nonempty line should contain the name of an existing file. 2802 Several such switches may be specified simultaneously. 2803 2804 2805 .. index:: --ignore (gnatmetric) 2806 2807 :switch:`--ignore={filename}` 2808 Do not process the sources listed in a specified file. 2809 2810 2811 .. index:: --verbose (gnatmetric) 2812 2813 :switch:`--verbose` 2814 Verbose mode; 2815 ``gnatmetric`` generates version information and then 2816 a trace of sources being processed. 2817 2818 2819 .. index:: --quiet (gnatmetric) 2820 2821 :switch:`--quiet` 2822 Quiet mode. 2823 2824 If a project file is specified and no argument source is explicitly 2825 specified (either directly or by means of :switch:`-files` option), and no 2826 :switch:`-U` is specified, then the set of processed sources is 2827 all the immediate units of the argument project. 2828 2829 2830 Legacy Switches 2831 ^^^^^^^^^^^^^^^ 2832 2833 Some switches have a short form, mostly for legacy reasons, 2834 as shown below. 2835 2836 .. index:: -x (gnatmetric) 2837 2838 :switch:`-x` 2839 :switch:`--generate-xml-output` 2840 2841 .. index:: -xs (gnatmetric) 2842 2843 :switch:`-xs` 2844 :switch:`--generate-xml-schema` 2845 2846 .. index:: -nt (gnatmetric) 2847 2848 :switch:`-nt` 2849 :switch:`--no-text-output` 2850 2851 .. index:: -d (gnatmetric) 2852 2853 :switch:`-d {output-dir}` 2854 :switch:`--output-dir` 2855 2856 .. index:: -o (gnatmetric) 2857 2858 :switch:`-o {file-suffix}` 2859 :switch:`--output-suffix` 2860 2861 .. index:: -og (gnatmetric) 2862 2863 :switch:`-og {file-name}` 2864 :switch:`--global-file-name` 2865 2866 .. index:: -ox (gnatmetric) 2867 2868 :switch:`-ox {file-name}` 2869 :switch:`--xml-file-name` 2870 2871 .. index:: -sfn (gnatmetric) 2872 2873 :switch:`-sfn` 2874 :switch:`--short-file-names` 2875 2876 .. index:: -W (gnatsmetric) 2877 2878 :switch:`-W{e}` 2879 :switch:`--wide-character-encoding={e}` 2880 2881 .. index:: -nolocal (gnatmetric) 2882 2883 :switch:`-nolocal` 2884 :switch:`--no-local-metrics` 2885 2886 .. index:: -ne (gnatmetric) 2887 2888 :switch:`-ne` 2889 :switch:`--no-treat-exit-as-goto` 2890 2891 .. index:: -files (gnatmetric) 2892 2893 :switch:`-files {filename}` 2894 :switch:`--files` 2895 2896 .. index:: -v (gnatmetric) 2897 2898 :switch:`-v` 2899 :switch:`--verbose` 2900 2901 .. index:: -q (gnatmetric) 2902 2903 :switch:`-q` 2904 :switch:`--quiet` 2905 2906.. only:: PRO or GPL 2907 2908 .. _The_GNAT_Pretty_Printer_gnatpp: 2909 2910 The GNAT Pretty Printer ``gnatpp`` 2911 ================================== 2912 2913 .. index:: ! gnatpp 2914 .. index:: pretty printer 2915 2916 The ``gnatpp`` tool is a utility for source reformatting / pretty 2917 printing. It takes an Ada source file as input and generates a 2918 reformatted version as output. You can specify various style 2919 directives via switches; e.g., identifier case conventions, rules of 2920 indentation, and comment layout. 2921 2922 ``gnatpp`` is a project-aware tool 2923 (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of 2924 the project-related switches). The project file package that can specify 2925 ``gnatpp`` switches is named ``Pretty_Printer``. 2926 2927 ``gnatpp`` cannot process sources that contain preprocessing 2928 directives. 2929 2930 The ``gnatpp`` command has the form 2931 2932 :: 2933 2934 $ gnatpp [ switches ] filename 2935 2936 where 2937 2938 * ``switches`` is an optional sequence of switches defining such properties as 2939 the formatting rules, the source search path, and the destination for the 2940 output source file 2941 2942 * ``filename`` is the name of the source file to reformat; wildcards 2943 or several file names on the same gnatpp command are allowed. The 2944 file name may contain path information; it does not have to follow 2945 the GNAT file naming rules 2946 2947 Note that it is no longer necessary to specify the Ada language version; 2948 ``gnatpp`` can process Ada source code written in any version from 2949 Ada 83 onward without specifying any language version switch. 2950 2951 2952 .. _Switches_for_gnatpp: 2953 2954 Switches for ``gnatpp`` 2955 ----------------------- 2956 2957 The following subsections describe the various switches accepted by 2958 ``gnatpp``, organized by category. 2959 2960 You specify a switch by supplying a name and generally also a value. 2961 In many cases the values for a switch with a given name are incompatible with 2962 each other 2963 (for example the switch that controls the casing of a reserved word may have 2964 exactly one value: upper case, lower case, or 2965 mixed case) and thus exactly one such switch can be in effect for an 2966 invocation of ``gnatpp``. 2967 If more than one is supplied, the last one is used. 2968 However, some values for the same switch are mutually compatible. 2969 You may supply several such switches to ``gnatpp``, but then 2970 each must be specified in full, with both the name and the value. 2971 Abbreviated forms (the name appearing once, followed by each value) are 2972 not permitted. 2973 2974 .. _Alignment_Control: 2975 2976 Alignment Control 2977 ^^^^^^^^^^^^^^^^^ 2978 2979 .. index:: Alignment control in gnatpp 2980 2981 Programs can be easier to read if certain constructs are vertically aligned. 2982 By default, alignment of the following constructs is set ON: 2983 2984 * ``:`` in declarations, 2985 * ``:=`` in initializations in declarations, 2986 * ``:=`` in assignment statements, 2987 * ``=>`` in associations, and 2988 * ``at`` keywords in the component clauses in record representation clauses. 2989 2990 In addition, ``in`` and ``out`` in parameter specifications are lined up. 2991 2992 .. index:: --no-alignment (gnatpp) 2993 .. index:: --alignment (gnatpp) 2994 .. index:: --no-align-modes (gnatpp) 2995 2996 2997 :switch:`--no-alignment` 2998 Set alignment to OFF 2999 3000 3001 :switch:`--alignment` 3002 Set alignment to ON 3003 3004 3005 :switch:`--no-align-modes` 3006 Do not line up ``in`` and ``out`` in parameter specifications. 3007 3008 .. _Casing_Control: 3009 3010 3011 Casing Control 3012 ^^^^^^^^^^^^^^ 3013 3014 .. index:: Casing control in gnatpp 3015 3016 ``gnatpp`` allows you to specify the casing for reserved words, 3017 pragma names, attribute designators and identifiers. 3018 For identifiers you may define a 3019 general rule for name casing but also override this rule 3020 via a set of dictionary files. 3021 3022 Three types of casing are supported: lower case, upper case, and mixed case. 3023 'Mixed case' means that the first letter, and also each letter immediately 3024 following an underscore, are converted to their uppercase forms; 3025 all the other letters are converted to their lowercase forms. 3026 3027 (Note: the casing switches are not yet fully supported in the 3028 libadalang-based version of gnatpp.) 3029 3030 .. index:: --name-case-as-declared (gnatpp) 3031 3032 :switch:`--name-case-as-declared` 3033 Name casing for defining occurrences are as they appear in the source file 3034 (this is the default) 3035 3036 .. index:: --name-upper-case (gnatpp) 3037 3038 :switch:`--name-upper-case` 3039 Names are in upper case 3040 3041 .. index:: --name-lower-case (gnatpp) 3042 3043 :switch:`--name-lower-case` 3044 Names are in lower case 3045 3046 .. index:: --name-mixed-case (gnatpp) 3047 3048 :switch:`--name-mixed-case` 3049 Names are in mixed case 3050 3051 .. index:: --attribute-lower-case (gnatpp) 3052 3053 :switch:`--attribute-lower-case` 3054 Attribute designators are lower case 3055 3056 .. index:: --attribute-upper-case (gnatpp) 3057 3058 :switch:`--attribute-upper-case` 3059 Attribute designators are upper case 3060 3061 .. index:: --attribute-mixed-case (gnatpp) 3062 3063 :switch:`--attribute-mixed-case` 3064 Attribute designators are mixed case (this is the default) 3065 3066 .. index:: --keyword-lower-case (gnatpp) 3067 3068 :switch:`--keyword-lower-case` 3069 Keywords (technically, these are known in Ada as *reserved words*) are 3070 lower case (this is the default) 3071 3072 .. index:: --keyword-upper-case (gnatpp) 3073 3074 :switch:`--keyword-upper-case` 3075 Keywords are upper case 3076 3077 .. index:: --enum-case-as-declared (gnatpp) 3078 3079 :switch:`--enum-case-as-declared` 3080 Enumeration literal casing for defining occurrences are as they appear in the 3081 source file. Overrides -n casing setting. 3082 3083 .. index:: --enum-upper-case (gnatpp) 3084 3085 :switch:`--enum-upper-case` 3086 Enumeration literals are in upper case. Overrides -n casing 3087 setting. 3088 3089 .. index:: --enum-lower-case (gnatpp) 3090 3091 :switch:`--enum-lower-case` 3092 Enumeration literals are in lower case. Overrides -n casing 3093 setting. 3094 3095 .. index:: --enum-mixed-case (gnatpp) 3096 3097 :switch:`--enum-mixed-case` 3098 Enumeration literals are in mixed case. Overrides -n casing 3099 setting. 3100 3101 .. index:: --type-case-as-declared (gnatpp) 3102 3103 :switch:`--type-case-as-declared` 3104 Names introduced by type and subtype declarations are always 3105 cased as they appear in the declaration in the source file. 3106 Overrides -n casing setting. 3107 3108 .. index:: --type-upper-case (gnatpp) 3109 3110 :switch:`--type-upper-case` 3111 Names introduced by type and subtype declarations are always in 3112 upper case. Overrides -n casing setting. 3113 3114 .. index:: --type-lower-case (gnatpp) 3115 3116 :switch:`--type-lower-case` 3117 Names introduced by type and subtype declarations are always in 3118 lower case. Overrides -n casing setting. 3119 3120 .. index:: --type-mixed-case (gnatpp) 3121 3122 :switch:`--type-mixed-case` 3123 Names introduced by type and subtype declarations are always in 3124 mixed case. Overrides -n casing setting. 3125 3126 .. index:: --number-upper-case (gnatpp) 3127 3128 :switch:`--number-upper-case` 3129 Names introduced by number declarations are always in 3130 upper case. Overrides -n casing setting. 3131 3132 .. index:: --number-lower-case (gnatpp) 3133 3134 :switch:`--number-lower-case` 3135 Names introduced by number declarations are always in 3136 lower case. Overrides -n casing setting. 3137 3138 .. index:: --number-mixed-case (gnatpp) 3139 3140 :switch:`--number-mixed-case` 3141 Names introduced by number declarations are always in 3142 mixed case. Overrides -n casing setting. 3143 3144 .. index:: --pragma-lower-case (gnatpp) 3145 3146 :switch:`--pragma-lower-case` 3147 Pragma names are lower case 3148 3149 .. index:: --pragma-upper-case (gnatpp) 3150 3151 :switch:`--pragma-upper-case` 3152 Pragma names are upper case 3153 3154 .. index:: --pragma-mixed-case (gnatpp) 3155 3156 :switch:`--pragma-mixed-case` 3157 Pragma names are mixed case (this is the default) 3158 3159 3160 .. index:: --syntax-only (gnatpp) 3161 3162 :switch:`--syntax-only` 3163 Disable the semantic analysis (name resolution) done by libadalang. 3164 This means gnatpp will not be able to support any of the 3165 "as-declared" switches. 3166 3167 3168 .. index:: --dictionary (gnatpp) 3169 3170 :switch:`--dictionary={file}` 3171 Use ``file`` as a *dictionary file* that defines 3172 the casing for a set of specified names, 3173 thereby overriding the effect on these names by 3174 any explicit or implicit 3175 -n switch. 3176 To supply more than one dictionary file, 3177 use several ``--dictionary`` switches. 3178 3179 ``gnatpp`` implicitly uses a *default dictionary file* 3180 to define the casing for the Ada predefined names and 3181 the names declared in the GNAT libraries. 3182 3183 3184 .. index:: --dictionary=- (gnatpp) 3185 3186 :switch:`--dictionary=-` 3187 Do not use the default dictionary file; 3188 instead, use the casing 3189 defined by a ``-n`` switch and any explicit 3190 dictionary file(s) 3191 3192 The structure of a dictionary file, and details on the conventions 3193 used in the default dictionary file, are defined in :ref:`Name_Casing`. 3194 3195 The :switch:`--dictionary=-` and 3196 :switch:`--dictionary={file}` switches are mutually 3197 compatible. 3198 3199 This group of ``gnatpp`` switches controls the layout of comments and 3200 complex syntactic constructs. See :ref:`Formatting_Comments` for details 3201 on their effect. 3202 3203 3204 .. index:: -c (gnatpp) 3205 3206 3207 :switch:`--comments-unchanged` 3208 All comments remain unchanged. 3209 3210 3211 :switch:`--comments-gnat-indentation` 3212 GNAT-style comment line indentation. 3213 This is the default. 3214 3215 3216 :switch:`--comments-gnat-beginning` 3217 GNAT-style comment beginning. 3218 3219 3220 :switch:`--comments-fill` 3221 Fill comment blocks. 3222 3223 3224 :switch:`--comments-special` 3225 Keep unchanged special form comments. 3226 This is the default. 3227 3228 3229 .. index:: --comments-only (gnatpp) 3230 3231 :switch:`--comments-only` 3232 Format just the comments. 3233 3234 .. index:: --no-end-id (gnatpp) 3235 3236 3237 :switch:`--no-end-id` 3238 Do not insert the name of a unit after ``end``; leave whatever comes 3239 after ``end``, if anything, alone. 3240 3241 .. index:: --no-separate-is (gnatpp) 3242 3243 3244 :switch:`--no-separate-is` 3245 Do not place the keyword ``is`` on a separate line in a subprogram body in 3246 case if the spec occupies more than one line. 3247 3248 .. index:: --separate-loop (gnatpp) 3249 3250 3251 :switch:`--separate-loop` 3252 Place the keyword ``loop`` in FOR and WHILE loop statements 3253 on a separate line. 3254 3255 .. index:: --no-separate-then (gnatpp) 3256 3257 3258 :switch:`--separate-then` 3259 Place the keyword ``then`` in IF statements 3260 on a separate line. 3261 3262 .. index:: --no-separate-loop (gnatpp) 3263 3264 3265 :switch:`--no-separate-loop` 3266 Do not place the keyword ``loop`` in FOR and WHILE loop statements 3267 on a separate line. This option is 3268 incompatible with the :switch:`--separate-loop` option. 3269 3270 .. index:: --no-separate-then (gnatpp) 3271 3272 3273 :switch:`--no-separate-then` 3274 Do not place the keyword ``then`` in IF statements 3275 on a separate line. This option is 3276 incompatible with the :switch:`--separate-then` option. 3277 3278 .. index:: --separate-loop-then (gnatpp) 3279 3280 3281 :switch:`--separate-loop-then` 3282 Equivalent to :switch:`--separate-loop` :switch:`--separate-then`. 3283 3284 .. index:: --no-separate-loop-then (gnatpp) 3285 3286 3287 :switch:`--no-separate-loop-then` 3288 Equivalent to :switch:`--no-separate-loop` :switch:`--no-separate-then`. 3289 3290 .. index:: --use-on-new-line (gnatpp) 3291 3292 3293 :switch:`--use-on-new-line` 3294 Start each USE clause in a context clause from a separate line. 3295 3296 3297 .. index:: --insert-blank-lines (gnatpp) 3298 3299 3300 :switch:`--insert-blank-lines` 3301 Insert blank lines where appropriate (between bodies and other large 3302 constructs). 3303 3304 .. index:: --preserve-blank-lines (gnatpp) 3305 3306 3307 :switch:`--preserve-blank-lines` 3308 Preserve blank lines in the input. By default, gnatpp will squeeze 3309 multiple blank lines down to one. 3310 3311 .. index:: --preserve-line-breaks (gnatpp) 3312 3313 :switch:`--preserve-line-breaks` 3314 Preserve line breaks in the input, to the extent possible. 3315 By default, line breaks are also inserted at appropriate 3316 places. 3317 3318 .. index:: --source-line-breaks (gnatpp) 3319 3320 :switch:`--source-line-breaks` 3321 Keep the line breaks from the source; do not insert or delete any 3322 line breaks. 3323 3324 .. index:: --spaces-only (gnatpp) 3325 3326 :switch:`--spaces-only` 3327 Disable all formatting except for inserting and removing spaces. 3328 This implies --source-line-breaks. 3329 3330 The ``--comments`` switches are compatible with one another, except 3331 that the ``--comments-unchanged`` switch disables all other comment 3332 formatting switches. 3333 3334 3335 .. _General_Text_Layout_Control: 3336 3337 General Text Layout Control 3338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3339 3340 These switches allow control over line length and indentation. 3341 3342 .. index:: --max-line-length (gnatpp) 3343 3344 :switch:`--max-line-length={nnn}` 3345 Maximum line length, ``nnn`` from 32...256, the default value is 79 3346 3347 3348 .. index:: --indentation (gnatpp) 3349 3350 :switch:`--indentation={nnn}` 3351 Indentation level, ``nnn`` from 1...9, the default value is 3 3352 3353 3354 .. index:: --indent-continuation (gnatpp) 3355 3356 :switch:`--indent-continuation={nnn}` 3357 Indentation level for continuation lines (relative to the line being 3358 continued), ``nnn`` from 1...9. 3359 The default 3360 value is one less than the (normal) indentation level, unless the 3361 indentation is set to 1 (in which case the default value for continuation 3362 line indentation is also 1) 3363 3364 3365 .. _Other_Formatting_Options: 3366 3367 Other Formatting Options 3368 ^^^^^^^^^^^^^^^^^^^^^^^^ 3369 3370 These switches control other formatting not listed above. 3371 3372 .. index:: --decimal-grouping (gnatpp) 3373 3374 :switch:`--decimal-grouping={n}` 3375 Put underscores in decimal literals (numeric literals without a base) 3376 every ``n`` characters. If a literal already has one or more 3377 underscores, it is not modified. For example, with 3378 ``--decimal-grouping=3``, ``1000000`` will be changed to 3379 ``1_000_000``. 3380 3381 3382 .. index:: --based-grouping (gnatpp) 3383 3384 :switch:`--based-grouping={n}` 3385 Same as ``--decimal-grouping``, but for based literals. For 3386 example, with ``--based-grouping=4``, ``16#0001FFFE#`` will be 3387 changed to ``16#0001_FFFE#``. 3388 3389 3390 .. index:: --split-line-before-record (gnatpp) 3391 3392 :switch:`--split-line-before-record` 3393 Split the line just before ``record`` in a record type declaration. 3394 3395 3396 .. index:: --indent-named-statements (gnatpp) 3397 3398 :switch:`--indent-named-statements` 3399 Named block and loop statements are indented with respect to 3400 the name. 3401 3402 3403 .. index:: --split-line-before-op (gnatpp) 3404 3405 :switch:`--split-line-before-op` 3406 If it is necessary to split a line at a binary operator, by default 3407 the line is split after the operator. With this option, it is split 3408 before the operator. 3409 3410 3411 .. index:: --RM-style-spacing (gnatpp) 3412 3413 :switch:`--RM-style-spacing` 3414 Do not insert an extra blank before various occurrences of 3415 '(' and ':'. This also turns off alignment. 3416 3417 3418 .. index:: --call_threshold (gnatpp) 3419 3420 :switch:`--call_threshold={nnn}` 3421 If the number of parameter associations is greater than ``nnn`` and if at 3422 least one association uses named notation, start each association from 3423 a new line. If ``nnn`` is 0, no check for the number of associations 3424 is made; this is the default. 3425 3426 3427 .. index:: --par_threshold (gnatpp) 3428 3429 :switch:`--par_threshold={nnn}` 3430 If the number of parameter specifications is greater than ``nnn`` 3431 (or equal to ``nnn`` in case of a function), start each specification from 3432 a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then 3433 the ``is`` is placed on a separate line. This feature is disabled by default. 3434 3435 .. index:: --vertical-enum-types (gnatpp) 3436 3437 :switch:`--vertical-enum-types` 3438 Format enumeration type declarations "vertically", e.g. each 3439 enumeration literal goes on a separate line. 3440 3441 .. index:: --vertical-array-types (gnatpp) 3442 3443 :switch:`--vertical-array-types` 3444 Format array type declarations "vertically", e.g. for 3445 multidimensional arrays, each index_subtype_definition or 3446 discrete_subtype_definition goes on a separate line. 3447 3448 .. index:: --vertical-named-aggregates (gnatpp) 3449 3450 :switch:`--vertical-named-aggregates` 3451 Format aggregates "vertically" if named notation is used for all 3452 component_associations, e.g. each component_association 3453 goes on a separate line. 3454 3455 .. index:: --vertical-case-alternatives (gnatpp) 3456 3457 :switch:`--vertical-case-alternatives` 3458 Format case statements, case expressions, and variant parts with 3459 additional line breaks. 3460 3461 3462 .. _Setting_the_Source_Search_Path: 3463 3464 Setting the Source Search Path 3465 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3466 3467 To define the search path for the input source file, ``gnatpp`` 3468 uses the same switches as the GNAT compiler, with the same effects: 3469 3470 .. index:: -I (gnatpp) 3471 3472 3473 :switch:`-I{dir}` 3474 3475 .. index:: -I- (gnatpp) 3476 3477 :switch:`-I-` 3478 3479 .. index:: -gnatec (gnatpp) 3480 3481 :switch:`-gnatec={path}` 3482 3483 3484 .. _Output_File_Control-gnatpp: 3485 3486 Output File Control 3487 ^^^^^^^^^^^^^^^^^^^ 3488 3489 By default the output overwrites the input file. 3490 The output may be redirected by the following switches: 3491 3492 3493 .. index:: --replace (gnatpp) 3494 3495 :switch:`--replace` 3496 This is the default. 3497 Replace the input source file with the reformatted output without 3498 creating any backup copy of the input source. 3499 3500 3501 .. index:: --output-dir (gnatpp) 3502 3503 :switch:`--output-dir={dir}` 3504 Generate output file in directory :file:`dir` with the same name as 3505 the input file. If :file:`dir` is the same as the directory 3506 containing the input file, the input file is not processed; use 3507 ``--replace`` if you want to update the input file in 3508 place. 3509 3510 3511 .. index:: --pipe (gnatpp) 3512 3513 :switch:`--pipe` 3514 Send the output to ``Standard_Output`` 3515 3516 3517 .. index:: --output (gnatpp) 3518 3519 :switch:`--output={output_file}` 3520 Write the output into ``output_file``. 3521 If ``output_file`` already exists, ``gnatpp`` terminates without 3522 reading or processing the input file. 3523 3524 3525 .. index:: --output-force (gnatpp) 3526 3527 :switch:`--output-force={output_file}` 3528 Write the output into ``output_file``, overwriting the existing file 3529 (if one is present). 3530 3531 3532 .. index:: --replace-backup (gnatpp) 3533 3534 :switch:`--replace-backup` 3535 Replace the input source file with the reformatted output, and copy the 3536 original input source into the file whose name is obtained by appending the 3537 :file:`.npp` suffix to the name of the input file. 3538 If a file with this name already exists, ``gnatpp`` terminates without 3539 reading or processing the input file. 3540 3541 3542 .. index:: --replace-force-backup (gnatpp) 3543 3544 :switch:`--replace-force-backup` 3545 Like ``--replace-backup`` except that if the file with the specified name 3546 already exists, it is overwritten. 3547 3548 3549 .. index:: --eol (gnatpp) 3550 3551 :switch:`--eol={xxx}` 3552 Specifies the line-ending style of the reformatted output file. The 3553 ``xxx`` string specified with the switch may be: 3554 3555 * *dos* - MS DOS style, lines end with CR LF characters* 3556 * *crlf* - the same as *dos* 3557 * *unix* - UNIX style, lines end with LF character* 3558 * *lf* - the same as *unix* 3559 3560 The default is to use the same end-of-line convention as the input. 3561 3562 .. index:: --wide-character-encoding (gnatpp) 3563 3564 :switch:`--wide-character-encoding={e}` 3565 Specify the wide character encoding method for the input and output 3566 files. ``e`` is one of the following: 3567 3568 * *8* - UTF-8 encoding 3569 3570 * *b* - Brackets encoding (default value) 3571 3572 Options ``--output-file`` and ``--output-force`` are allowed only if 3573 the call to gnatpp contains only one file to reformat. 3574 3575 Option ``--eol`` and ``--wide-character-encoding`` cannot be used together 3576 with the ``--pipe`` option. 3577 3578 3579 .. _Other_gnatpp_Switches: 3580 3581 Other ``gnatpp`` Switches 3582 ^^^^^^^^^^^^^^^^^^^^^^^^^ 3583 3584 The additional ``gnatpp`` switches are defined in this subsection. 3585 3586 3587 .. index:: --version (gnatpp) 3588 3589 :switch:`--version` 3590 Display copyright and version, then exit disregarding all other options. 3591 3592 3593 .. index:: --help (gnatpp) 3594 3595 :switch:`--help` 3596 Display usage, then exit disregarding all other options. 3597 3598 3599 .. index:: -P (gnatpp) 3600 3601 :switch:`-P {file}` 3602 Indicates the name of the project file that describes the set of sources 3603 to be processed. The exact set of argument sources depends on other options 3604 specified; see below. 3605 3606 3607 .. index:: -U (gnatpp) 3608 3609 :switch:`-U` 3610 If a project file is specified and no argument source is explicitly 3611 specified (either directly or by means of ``--files`` option), process 3612 all the units of the closure of the argument project. Otherwise this option 3613 has no effect. 3614 3615 3616 :switch:`-U {main_unit}` 3617 If a project file is specified and no argument source is explicitly 3618 specified (either directly or by means of ``--files`` option), process 3619 the closure of units rooted at ``main_unit``. Otherwise this option 3620 has no effect. 3621 3622 3623 .. index:: -X (gnatpp) 3624 3625 :switch:`-X{name}={value}` 3626 Indicates that external variable ``name`` in the argument project 3627 has the value ``value``. Has no effect if no project is specified. 3628 3629 3630 .. index:: --RTS (gnatpp) 3631 3632 :switch:`--RTS={rts-path}` 3633 Specifies the default location of the runtime library. Same meaning as the 3634 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). 3635 3636 3637 .. index:: --incremental (gnatpp) 3638 3639 :switch:`--incremental` 3640 Incremental processing on a per-file basis. Source files are only 3641 processed if they have been modified, or if files they depend on have 3642 been modified. This is similar to the way gnatmake/gprbuild only 3643 compiles files that need to be recompiled. A project file is required 3644 in this mode, and the gnat driver (as in *gnat pretty*) is not 3645 supported. 3646 (Note: this switch is not yet supported in the libadalang-based 3647 version of gnatpp.) 3648 3649 3650 .. index:: --pp-off (gnatpp) 3651 3652 :switch:`--pp-off={xxx}` 3653 Use :switch:`--xxx` as the command to turn off pretty printing, instead 3654 of the default ``--!pp off``. 3655 3656 3657 .. index:: --pp-on (gnatpp) 3658 3659 :switch:`--pp-on={xxx}` 3660 Use :switch:`--xxx` as the command to turn pretty printing back on, instead 3661 of the default ``--!pp on``. 3662 3663 3664 .. index:: --files (gnatpp) 3665 3666 :switch:`--files={filename}` 3667 Take as arguments the files listed in text file ``file``. 3668 Text file ``file`` may contain empty lines that are ignored. 3669 Each nonempty line should contain the name of an existing file. 3670 Several such switches may be specified simultaneously. 3671 3672 3673 .. index:: --ignore (gnatpp) 3674 3675 :switch:`--ignore={filename}` 3676 Do not process the sources listed in a specified file. This option cannot 3677 be used in incremental mode. 3678 3679 .. index:: --jobs (gnatpp) 3680 3681 :switch:`--jobs={n}` 3682 With ``--incremental``, use *n* ``gnatpp`` processes to perform 3683 pretty printing in parallel. If *n* is 0, then the maximum number 3684 processes is the number of core processors on the platform. 3685 3686 3687 .. index:: --verbose (gnatpp) 3688 3689 :switch:`--verbose` 3690 Verbose mode 3691 3692 3693 .. index:: --quiet (gnatpp) 3694 3695 :switch:`--quiet` 3696 Quiet mode 3697 3698 If a project file is specified and no argument source is explicitly 3699 specified (either directly or by means of ``--files`` option), and no 3700 ``-U`` is specified, then the set of processed sources is 3701 all the immediate units of the argument project. 3702 3703 3704 .. _Formatting_Rules: 3705 3706 Formatting Rules 3707 ---------------- 3708 3709 The following subsections show how ``gnatpp`` treats white space, 3710 comments, program layout, and name casing. 3711 They provide detailed descriptions of the switches shown above. 3712 3713 3714 .. _Disabling_Pretty_Printing: 3715 3716 Disabling Pretty Printing 3717 ^^^^^^^^^^^^^^^^^^^^^^^^^ 3718 3719 Pretty printing is highly heuristic in nature, and sometimes doesn't 3720 do exactly what you want. If you wish to format a certain region of 3721 code by hand, you can turn off pretty printing in that region by 3722 surrounding it with special comments that start with ``--!pp off`` 3723 and ``--!pp on``. The text in that region will then be reproduced 3724 verbatim in the output with no formatting. 3725 3726 To disable pretty printing for the whole file, put ``--!pp off`` at 3727 the top, with no following ``--!pp on``. 3728 3729 The comments must appear on a line by themselves, with nothing 3730 preceding except spaces. The initial text of the comment must be 3731 exactly ``--!pp off`` or ``--!pp on`` (case sensitive), but may 3732 be followed by arbitrary additional text. For example: 3733 3734 .. code-block:: ada 3735 3736 package Interrupts is 3737 --!pp off -- turn off pretty printing so "Interrupt_Kind" lines up 3738 type Interrupt_Kind is 3739 (Asynchronous_Interrupt_Kind, 3740 Synchronous_Interrupt_Kind, 3741 Green_Interrupt_Kind); 3742 --!pp on -- reenable pretty printing 3743 ... 3744 3745 You can specify different comment strings using the ``--pp-off`` 3746 and ``--pp-on`` switches. For example, if you say: 3747 3748 :: 3749 3750 $ gnatpp --pp-off=' pp-' *.ad? 3751 3752 then gnatpp will recognize comments of the form 3753 ``-- pp-`` instead of ``--!pp off`` for disabling pretty 3754 printing. Note that the leading ``--`` of the comment is not 3755 included in the argument to these switches. 3756 3757 3758 .. _White_Space_and_Empty_Lines: 3759 3760 White Space and Empty Lines 3761 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3762 3763 ``gnatpp`` does not have an option to control space characters. 3764 It will add or remove spaces according to the style illustrated by the 3765 examples in the :title:`Ada Reference Manual`. 3766 The output file will contain no lines with trailing white space. 3767 3768 By default, a sequence of one or more blank lines in the input is 3769 converted to a single blank line in the output; multiple blank lines 3770 are squeezed down to one. 3771 The ``--preserve-blank-lines`` option 3772 turns off the squeezing; each blank line in the input is copied 3773 to the output. 3774 The ``--insert-blank-lines`` option 3775 causes additional blank lines to be inserted if not already 3776 present in the input (e.g. between bodies). 3777 3778 3779 .. _Formatting_Comments: 3780 3781 Formatting Comments 3782 ^^^^^^^^^^^^^^^^^^^ 3783 3784 Comments in Ada code are of two kinds: 3785 3786 * a *whole-line comment*, which appears by itself (possibly preceded by 3787 white space) on a line 3788 3789 * an *end-of-line comment*, which follows some other Ada code on 3790 the same line. 3791 3792 A whole-line comment is indented according to the surrounding code, 3793 with some exceptions. Comments that start in column 1 are kept 3794 there. If possible, comments are not moved so far to the right that 3795 the maximum line length is exceeded. The ``--comments-unchanged`` 3796 option turns off comment formatting. Special-form comments such as 3797 SPARK-style ``--#...`` are left alone. 3798 3799 For an end-of-line comment, ``gnatpp`` tries to leave the same 3800 number of spaces between the end of the preceding Ada code and the 3801 beginning of the comment as appear in the original source. 3802 3803 The ``--comments-gnat-beginning`` switch (GNAT style comment 3804 beginning) has the following effect: 3805 3806 * For each whole-line comment that does not end with two hyphens, 3807 ``gnatpp`` inserts spaces if necessary after the starting two 3808 hyphens to ensure that there are at least two spaces between 3809 these hyphens and the first non-blank character of the comment. 3810 3811 The ``--comments-fill`` switch specifies that whole-line comments 3812 that form a paragraph will be filled in typical word processor style 3813 (that is, moving words between lines to make the lines other than the 3814 last similar in length ). 3815 3816 The ``--comments-only`` switch specifies that only the comments are 3817 formatted; the rest of the program text is left alone. The comments 3818 are formatted according to the ``--comments-gnat-beginning`` and 3819 ``--comments-fill`` switches; other formatting switches are ignored. For 3820 example, ``--comments-only --comments-fill`` means to fill comment 3821 paragraphs, and do nothing else. Likewise, ``--comments-only 3822 --comments-gnat-beginning`` ensures comments start with at least two 3823 spaces after ``--``, and ``--comments-only --comments-gnat-beginning 3824 --comments-fill`` does both. If ``--comments-only`` is given without 3825 ``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp 3826 doesn't format anything. 3827 3828 3829 .. _Name_Casing: 3830 3831 Name Casing 3832 ^^^^^^^^^^^ 3833 3834 ``gnatpp`` always converts the usage occurrence of a (simple) name to 3835 the same casing as the corresponding defining identifier. 3836 3837 You control the casing for defining occurrences via the ``--name...`` 3838 switches. With ``--name-case-as-declared``, which is the default, 3839 defining occurrences appear exactly as in the source file where they 3840 are declared. The other values for this switch -- 3841 ``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case`` 3842 -- result in upper, lower, or mixed case, respectively. If 3843 ``gnatpp`` changes the casing of a defining occurrence, it 3844 analogously changes the casing of all the usage occurrences of this 3845 name. 3846 3847 If the defining occurrence of a name is not in the source compilation 3848 unit currently being processed by ``gnatpp``, the casing of each 3849 reference to this name is changed according to the switch (subject to 3850 the dictionary file mechanism described below). Thus ``gnatpp`` acts 3851 as though the switch had affected the casing for the defining 3852 occurrence of the name. 3853 3854 The options 3855 :switch:`--attribute...`, 3856 :switch:`--keyword...`, 3857 :switch:`--enum...`, 3858 :switch:`--type...`, 3859 :switch:`--number...`, and 3860 :switch:`--pragma...` 3861 allow finer-grained control over casing for 3862 attributes, keywords, enumeration literals, 3863 types, named numbers and pragmas, respectively. 3864 :switch:`--type...` cover subtypes as well. 3865 3866 Some names may need to be spelled with casing conventions that are not 3867 covered by the upper-, lower-, and mixed-case transformations. 3868 You can arrange correct casing by placing such names in a 3869 *dictionary file*, 3870 and then supplying a ``--dictionary`` switch. 3871 The casing of names from dictionary files overrides 3872 any ``--name...`` switch. 3873 3874 To handle the casing of Ada predefined names and the names from GNAT libraries, 3875 ``gnatpp`` assumes a default dictionary file. 3876 The name of each predefined entity is spelled with the same casing as is used 3877 for the entity in the :title:`Ada Reference Manual` (usually mixed case). 3878 The name of each entity in the GNAT libraries is spelled with the same casing 3879 as is used in the declaration of that entity. 3880 3881 The ``--dictionary=-`` switch suppresses the use of 3882 the default dictionary file. Instead, the casing for predefined and 3883 GNAT-defined names will be established by the 3884 ``-n`` switch or explicit dictionary files. For 3885 example, by default the names ``Ada.Text_IO`` and 3886 ``GNAT.OS_Lib`` will appear as just shown, even in the presence of 3887 a ``--name-upper-case`` switch. To ensure that even 3888 such names are rendered in uppercase, additionally supply the 3889 --dictionary=- switch (or else place these names 3890 in upper case in a dictionary file). 3891 3892 A dictionary file is a plain text file; each line in this file can be 3893 either a blank line (containing only space characters), an Ada comment 3894 line, or the specification of exactly one *casing schema*. 3895 3896 A casing schema is a string that has the following syntax: 3897 3898 :: 3899 3900 casing_schema ::= identifier | simple_identifier 3901 3902 simple_identifier ::= letter{letter_or_digit} 3903 3904 3905 (See :title:`Ada Reference Manual`, Section 2.3) for the definition of the 3906 ``identifier`` lexical element and the ``letter_or_digit`` category.) 3907 3908 The casing schema string can be followed by white space and/or an Ada-style 3909 comment; any amount of white space is allowed before the string. 3910 3911 If a dictionary file is passed as 3912 the value of a :switch:`--dictionary={file}` switch 3913 then for every 3914 simple name and every identifier, ``gnatpp`` checks if the dictionary 3915 defines the casing for the name or for some of its parts (the term 'subword' 3916 is used below to denote the part of a name which is delimited by '_' or by 3917 the beginning or end of the word and which does not contain any '_' inside): 3918 3919 * if the whole name is in the dictionary, ``gnatpp`` uses for this name 3920 the casing defined by the dictionary; no subwords are checked for this word 3921 3922 * for every subword ``gnatpp`` checks if the dictionary contains the 3923 corresponding string of the form ``simple_identifier``, 3924 and if it does, the casing of this ``simple_identifier`` is used 3925 for this subword 3926 3927 * if the whole name does not contain any '_' inside, and if for this name 3928 the dictionary contains two entries -- one of the form ``identifier``, 3929 and another of the form ``simple_identifier`` -- then the first one 3930 is applied to define the casing of this name 3931 3932 * if more than one dictionary file is passed as ``gnatpp`` switches, each 3933 dictionary adds new casing exceptions and overrides all the existing casing 3934 exceptions set by the previous dictionaries 3935 3936 * when ``gnatpp`` checks if the word or subword is in the dictionary, 3937 this check is not case sensitive 3938 3939 For example, suppose we have the following source to reformat: 3940 3941 .. code-block:: ada 3942 3943 procedure test is 3944 name1 : integer := 1; 3945 name4_name3_name2 : integer := 2; 3946 name2_name3_name4 : Boolean; 3947 name1_var : Float; 3948 begin 3949 name2_name3_name4 := name4_name3_name2 > name1; 3950 end; 3951 3952 And suppose we have two dictionaries: 3953 3954 :: 3955 3956 *dict1:* 3957 NAME1 3958 *NaMe3* 3959 *Name1* 3960 3961 *dict2:* 3962 *NAME3* 3963 3964 If ``gnatpp`` is called with the following switches: 3965 3966 :: 3967 3968 $ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb 3969 3970 then we will get the following name casing in the ``gnatpp`` output: 3971 3972 3973 .. code-block:: ada 3974 3975 procedure Test is 3976 NAME1 : Integer := 1; 3977 Name4_NAME3_Name2 : Integer := 2; 3978 Name2_NAME3_Name4 : Boolean; 3979 Name1_Var : Float; 3980 begin 3981 Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; 3982 end Test; 3983 3984 .. _Preprocessor_directives: 3985 3986 Preprocessor Directives 3987 ^^^^^^^^^^^^^^^^^^^^^^^ 3988 3989 ``gnatpp`` has some support for preprocessor directives. 3990 You can use preprocessor symbols, as in ``$symbol``. 3991 In addition, you can use conditional compilation, 3992 so long as the program text is syntactically legal Ada code 3993 after removing all the preprocessor directives (lines starting 3994 with ``#``). For example, ``gnatpp`` can format the following: 3995 3996 .. code-block:: ada 3997 3998 package P is 3999 #IF SOMETHING 4000 X : constant Integer := 123; 4001 #ELSE 4002 X : constant Integer := 456; 4003 #END IF; 4004 end P; 4005 4006 which will be formatted as if it were: 4007 4008 .. code-block:: ada 4009 4010 package P is 4011 X : constant Integer := 123; 4012 X : constant Integer := 456; 4013 end P; 4014 4015 except that the ``#`` lines will be preserved. 4016 However, ``gnatpp`` cannot format the following: 4017 4018 .. code-block:: ada 4019 4020 procedure P is 4021 begin 4022 #IF SOMETHING 4023 if X = 0 then 4024 #ELSE 4025 if X = 1 then 4026 #END IF; 4027 null; 4028 end if; 4029 end P; 4030 4031 because removing the ``#`` lines gives: 4032 4033 .. code-block:: ada 4034 4035 procedure P is 4036 begin 4037 if X = 0 then 4038 if X = 1 then 4039 null; 4040 end if; 4041 end P; 4042 4043 which is not syntactically legal. 4044 4045 Legacy Switches 4046 ^^^^^^^^^^^^^^^ 4047 4048 Some switches have a short form, mostly for legacy reasons, 4049 as shown below. 4050 4051 .. index:: -n (gnatpp) 4052 4053 :switch:`-nD` 4054 :switch:`--name-case-as-declared` 4055 4056 :switch:`-nU` 4057 :switch:`--name-upper-case` 4058 4059 :switch:`-nL` 4060 :switch:`--name-lower-case` 4061 4062 :switch:`-nM` 4063 :switch:`--name-mixed-case` 4064 4065 .. index:: -a (gnatpp) 4066 4067 :switch:`-aL` 4068 :switch:`--attribute-lower-case` 4069 4070 :switch:`-aU` 4071 :switch:`--attribute-upper-case` 4072 4073 :switch:`-aM` 4074 :switch:`--attribute-mixed-case` 4075 4076 .. index:: -k (gnatpp) 4077 4078 :switch:`-kL` 4079 :switch:`--keyword-lower-case` 4080 4081 :switch:`-kU` 4082 :switch:`--keyword-upper-case` 4083 4084 .. index:: -ne (gnatpp) 4085 4086 :switch:`-neD` 4087 :switch:`--enum-case-as-declared` 4088 4089 :switch:`-neU` 4090 :switch:`--enum-upper-case` 4091 4092 :switch:`-neL` 4093 :switch:`--enum-lower-case` 4094 4095 :switch:`-neM` 4096 :switch:`--enum-mixed-case` 4097 4098 .. index:: -nt (gnatpp) 4099 4100 :switch:`-ntD` 4101 :switch:`--type-case-as-declared` 4102 4103 :switch:`-ntU` 4104 :switch:`--type-upper-case` 4105 4106 :switch:`-ntL` 4107 :switch:`--type-lower-case` 4108 4109 :switch:`-ntM` 4110 :switch:`--type-mixed-case` 4111 4112 :switch:`-nnU` 4113 :switch:`--number-upper-case` 4114 4115 :switch:`-nnL` 4116 :switch:`--number-lower-case` 4117 4118 :switch:`-nnM` 4119 :switch:`--number-mixed-case` 4120 4121 .. index:: -p (gnatpp) 4122 4123 :switch:`-pL` 4124 :switch:`--pragma-lower-case` 4125 4126 :switch:`-pU` 4127 :switch:`--pragma-upper-case` 4128 4129 :switch:`-pM` 4130 :switch:`--pragma-mixed-case` 4131 4132 .. index:: -D (gnatpp) 4133 4134 :switch:`-D{file}` 4135 :switch:`--dictionary={file}` 4136 4137 .. index:: -D- (gnatpp) 4138 4139 :switch:`-D-` 4140 :switch:`--dictionary=-` 4141 4142 .. index:: -c (gnatpp) 4143 4144 :switch:`-c0` 4145 :switch:`--comments-unchanged` 4146 4147 :switch:`-c1` 4148 :switch:`--comments-gnat-indentation` 4149 4150 :switch:`-c3` 4151 :switch:`--comments-gnat-beginning` 4152 4153 :switch:`-c4` 4154 :switch:`--comments-fill` 4155 4156 :switch:`-c5` 4157 :switch:`--comments-special` 4158 4159 .. index:: -M (gnatpp) 4160 4161 :switch:`-M{nnn}` 4162 :switch:`--max-line-length={nnn}` 4163 4164 .. index:: -i (gnatpp) 4165 4166 :switch:`-i{nnn}` 4167 :switch:`--indentation={nnn}` 4168 4169 .. index:: -cl (gnatpp) 4170 4171 :switch:`-cl{nnn}` 4172 :switch:`--indent-continuation={nnn}` 4173 4174 .. index:: -pipe (gnatpp) 4175 4176 :switch:`-pipe` 4177 :switch:`--pipe` 4178 4179 .. index:: -o (gnatpp) 4180 4181 :switch:`-o {output-file}` 4182 :switch:`--output={output-file}` 4183 4184 .. index:: -of (gnatpp) 4185 4186 :switch:`-of {output-file}` 4187 :switch:`--output-force={output-file}` 4188 4189 .. index:: -r (gnatpp) 4190 4191 :switch:`-rnb` 4192 :switch:`--replace` 4193 4194 :switch:`-r` 4195 :switch:`--replace-backup` 4196 4197 .. index:: -rf (gnatpp) 4198 4199 :switch:`-rf` 4200 :switch:`--replace-force-backup` 4201 4202 .. index:: -rnb (gnatpp) 4203 4204 .. index:: --eol (gnatpp) 4205 4206 .. index:: -W (gnatpp) 4207 4208 :switch:`-W{e}` 4209 :switch:`--wide-character-encoding={e}` 4210 4211 .. index:: -files (gnatpp) 4212 4213 :switch:`-files {filename}` 4214 :switch:`--files={filename}` 4215 4216 .. index:: -j (gnatpp) 4217 4218 :switch:`-j{n}` 4219 :switch:`--jobs={n}` 4220 4221 .. index:: -v (gnatpp) 4222 4223 :switch:`-v` 4224 :switch:`--verbose` 4225 4226 .. index:: -q (gnatpp) 4227 4228 :switch:`-q` 4229 :switch:`--quiet` 4230 4231 4232.. only:: PRO or GPL 4233 4234 .. _The_Body_Stub_Generator_gnatstub: 4235 4236 The Body Stub Generator *gnatstub* 4237 ================================== 4238 4239 .. index:: ! gnatstub 4240 4241 ``gnatstub`` creates empty but compilable bodies 4242 for library unit declarations, and empty but compilable 4243 subunits for body stubs. 4244 4245 ``gnatstub`` is a project-aware tool. 4246 (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of 4247 the project-related switches but note that ``gnatstub`` does not support 4248 the :switch:`-U`, :switch:`-U {main_unit}`, :switch:`--subdirs={dir}`, or 4249 :switch:`--no_objects_dir` switches.) 4250 The project file package that can specify 4251 ``gnatstub`` switches is named ``gnatstub``. 4252 4253 4254 By default, all the program unit bodies generated by ``gnatstub`` 4255 raise ``Program_Error``, which will catch accidental calls of 4256 generated stubs. This behavior can be changed with option 4257 ``--no-exception`` (see below). 4258 4259 .. _Running_gnatstub: 4260 4261 Running ``gnatstub`` 4262 -------------------- 4263 4264 ``gnatstub`` invocation has the following form: 4265 4266 :: 4267 4268 $ gnatstub [ switches ] {filename} 4269 4270 where 4271 4272 * *filename* 4273 is the name of the source file that contains a library unit declaration 4274 for which a body must be created or a library unit body for which subunits 4275 must be created for the body stubs declared in this body. 4276 The file name may contain path information. 4277 If the name does not follow GNAT file naming conventions and the set 4278 of switches does not contain a project file that defines naming 4279 conventions, the name of the body file must 4280 be provided 4281 explicitly as the value of the :switch:`--output={body-name}` option. 4282 If the file name follows the GNAT file naming 4283 conventions and the name of the body file is not provided, 4284 ``gnatstub`` 4285 takes the naming conventions for the generated source from the 4286 project file provided as a parameter of ``-P`` switch if any, 4287 or creates the name file to generate using the standard GNAT 4288 naming conventions. 4289 4290 Note that it is no longer necessary to specify the Ada language version; 4291 ``gnatmetric`` can process Ada source code written in any version from 4292 Ada 83 onward without specifying any language version switch. 4293 4294 * *switches* 4295 is an optional sequence of switches as described in the next section 4296 4297 4298 .. _Switches_for_gnatstub: 4299 4300 Switches for ``gnatstub`` 4301 ------------------------- 4302 4303 .. index:: --version (gnatstub) 4304 4305 :switch:`--version` 4306 Display copyright and version, then exit disregarding all other options. 4307 4308 4309 .. index:: --help (gnatstub) 4310 4311 :switch:`--help` 4312 Display usage, then exit disregarding all other options. 4313 4314 4315 .. index:: -P (gnatstub) 4316 4317 :switch:`-P {file}` 4318 Indicates the name of the project file that describes the set of sources 4319 to be processed. An aggregate project is allowed as the file parameter only 4320 if it has exactly one non-aggregate project being aggregated. 4321 4322 4323 .. index:: -X (gnatstub) 4324 4325 :switch:`-X{name}={value}` 4326 Indicates that external variable ``name`` in the argument project 4327 has the value ``value``. Has no effect if no project is specified. 4328 4329 4330 .. index:: --RTS (gnatstub) 4331 4332 :switch:`--RTS={rts-path}` 4333 Specifies the default location of the runtime library. Same meaning as the 4334 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). 4335 4336 4337 .. index:: --subunits (gnatstub) 4338 4339 :switch:`--subunits` 4340 Generate subunits for body stubs. If this switch is specified, 4341 ``gnatstub`` expects a library unit body as an argument file; 4342 otherwise a library unit declaration is expected. If a body stub 4343 already has a corresponding subunit, ``gnatstub`` does not 4344 generate anything for it. 4345 4346 4347 .. index:: --force (gnatstub) 4348 4349 :switch:`--force` 4350 If the destination directory already contains a file with the name of the 4351 body file 4352 for the argument spec file, replace it with the generated body stub. 4353 This switch cannot be used together with ``--subunits``. 4354 4355 4356 .. index:: --comment-header-spec (gnatstub) 4357 4358 :switch:`--comment-header-spec` 4359 Put the comment header (i.e., all the comments preceding the 4360 compilation unit) from the source of the library unit declaration 4361 into the body stub. 4362 4363 4364 .. index:: --comment-header-sample (gnatstub) 4365 4366 :switch:`--comment-header-sample` 4367 Put a sample comment header into the body stub. 4368 4369 4370 .. index:: --header-file (gnatstub) 4371 4372 :switch:`--header-file={filename}` 4373 Use the content of the file as the comment header for a generated body stub. 4374 4375 4376 .. index:: --max-line-length (gnatstub) 4377 4378 :switch:`--max-line-length={n}` 4379 (``n`` is a non-negative integer). Set the maximum line length for 4380 the output files. The default is 79. The maximum value that can be 4381 specified is 32767. 4382 4383 4384 .. index:: --indentation (gnatstub) 4385 4386 :switch:`--indentation={n}` 4387 (``n`` is an integer from 1 to 9). Set the indentation level in 4388 the generated files to ``n``. 4389 The default indentation is 3. 4390 4391 4392 .. index:: --alphabetical-order (gnatstub) 4393 4394 :switch:`--alphabetical-order` 4395 Order local bodies alphabetically. (By default local bodies are ordered 4396 in the same way as the corresponding local specs in the argument 4397 spec file.) 4398 4399 4400 .. index:: --no-exception (gnatstub) 4401 4402 :switch:`--no-exception` 4403 Avoid raising Program_Error in the generated bodies of program unit stubs, 4404 except in the case of functions, where we have no value to return. 4405 4406 4407 .. index:: --no-local-header (gnatstub) 4408 4409 :switch:`--no-local-header` 4410 Do not place local comment header with unit name before body stub for a 4411 unit. 4412 4413 4414 .. index:: --files (gnatstub) 4415 4416 :switch:`--files={filename}` 4417 Take as arguments the files listed in text file ``file``. 4418 Text file ``file`` may contain empty lines that are ignored. 4419 Each nonempty line should contain the name of an existing file. 4420 Several such switches may be specified. 4421 4422 4423 .. index:: --output (gnatstub) 4424 4425 :switch:`--output={body-name}` 4426 Body file name. This should be set if the argument file name does 4427 not follow the default GNAT file naming conventions, and the naming 4428 conventions are not specified by a project file. If this switch and 4429 ``-P`` are both omitted, the name for the body will be obtained 4430 according to the default GNAT file naming conventions. 4431 4432 4433 .. index:: --output-dir (gnatstub) 4434 4435 :switch:`--output-dir={dir-name}` 4436 The directory in which to place the output files. 4437 If this switch is not set, the generated library unit body is 4438 placed in the current directory, and generated sununits 4439 in the directory where the argument body is located. 4440 4441 4442 .. index:: --wide-character-encoding (gnatstub) 4443 4444 :switch:`--wide-character-encoding={e}` 4445 Specify the wide character encoding method for the input and output 4446 files. ``e`` is one of the following: 4447 4448 * *8* - UTF-8 encoding 4449 4450 * *b* - Brackets encoding (default value) 4451 4452 4453 .. index:: --quiet (gnatstub) 4454 .. index:: -q (gnatstub) 4455 4456 :switch:`--quiet` / :switch:`-q` 4457 Quiet mode. 4458 4459 4460 .. index:: --verbose (gnatstub) 4461 .. index:: -v (gnatstub) 4462 4463 :switch:`--verbose` / :switch:`-v` 4464 Verbose mode. 4465 4466 Legacy Switches 4467 ^^^^^^^^^^^^^^^ 4468 4469 Some switches have a short form, mostly for legacy reasons, 4470 as shown below. 4471 4472 .. index:: -M (gnatstub) 4473 4474 :switch:`-gnatyM{nnn}` 4475 :switch:`--max-line-length={nnn}` 4476 4477 .. index:: -i (gnatstub) 4478 4479 :switch:`-i{nnn}` 4480 :switch:`--indentation={nnn}` 4481 4482 .. index:: -gnaty (gnatstub) 4483 4484 :switch:`-gnaty{nnn}` 4485 :switch:`--indentation={nnn}` 4486 4487 .. index:: -f (gnatstub) 4488 4489 :switch:`-f` 4490 :switch:`--force` 4491 4492 .. index:: -gnatyo (gnatstub) 4493 4494 :switch:`-gnatyo` 4495 :switch:`--alphabetical-order` 4496 4497 .. index:: -hg (gnatstub) 4498 4499 :switch:`-hg` 4500 :switch:`--comment-header-sample` 4501 4502 .. index:: -hs (gnatstub) 4503 4504 :switch:`-hs` 4505 :switch:`--comment-header-spec` 4506 4507 .. index:: -o (gnatstub) 4508 4509 :switch:`-o {output-file}` 4510 :switch:`--output={output-file}` 4511 4512 .. index:: -dir (gnatstub) 4513 4514 :switch:`-dir {dir-name}` 4515 :switch:`--output-dir={dir-name}` 4516 4517 .. index:: -W (gnatstub) 4518 4519 :switch:`-W{e}` 4520 :switch:`--wide-character-encoding={e}` 4521 4522 .. index:: -files (gnatstub) 4523 4524 :switch:`-files {filename}` 4525 :switch:`--files={filename}` 4526 4527 4528.. only:: PRO or GPL 4529 4530 .. _The_Unit_Test_Generator_gnattest: 4531 4532 The Unit Test Generator ``gnattest`` 4533 ==================================== 4534 4535 .. index:: ! gnattest 4536 4537 ``gnattest`` is an ASIS-based utility that creates unit-test skeletons 4538 as well as a test driver infrastructure (harness). ``gnattest`` creates 4539 a skeleton for each visible subprogram in the packages under consideration when 4540 they do not exist already. 4541 4542 ``gnattest`` is a project-aware tool. 4543 (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of 4544 the project-related switches but note that ``gnattest`` does not support 4545 the :switch:`-U`, :switch:`-eL`, :switch:`--subdirs={dir}`, or 4546 :switch:`--no_objects_dir` switches.) 4547 The project file package that can specify 4548 ``gnattest`` switches is named ``gnattest``. 4549 4550 The user can choose to generate a single test driver 4551 that will run all individual tests, or separate test drivers for each test. The 4552 second option allows much greater flexibility in test execution environment, 4553 allows to benefit from parallel tests execution to increase performance, and 4554 provides stubbing support. 4555 4556 ``gnattest`` also has a mode of operation where it acts as the test 4557 aggregator when multiple test executables must be run, in particular when 4558 the separate test drivers were generated. In this mode it handles individual 4559 tests execution and upon completion reports the summary results of the test 4560 run. 4561 4562 In order to process source files from a project, ``gnattest`` has to 4563 semantically analyze the sources. Therefore, test skeletons can only be 4564 generated for legal Ada units. If a unit is dependent on other units, 4565 those units should be among the source files of the project or of other projects 4566 imported by this one. 4567 4568 Generated skeletons and harnesses are based on the AUnit testing framework. 4569 AUnit is an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit 4570 for Java or CppUnit for C++. While it is advised that gnattest users read 4571 the AUnit manual, deep knowledge of AUnit is not necessary for using ``gnattest``. 4572 For correct operation of ``gnattest``, AUnit should be installed and 4573 aunit.gpr must be on the project path. Except for some special circumstances 4574 (e.g. a custom run-time is used), this should normally be the case out of the box. 4575 4576 4577 .. _Running_gnattest: 4578 4579 Running ``gnattest`` 4580 -------------------- 4581 4582 There are two ways of running ``gnattest``. 4583 4584 .. _Framework_Generation_Mode: 4585 4586 Framework Generation Mode 4587 ^^^^^^^^^^^^^^^^^^^^^^^^^ 4588 4589 In this mode ``gnattest`` has the following command-line interface: 4590 4591 :: 4592 4593 $ gnattest -Pprojname [ switches ] [ filename ] [ -cargs gcc_switches ] 4594 4595 where 4596 4597 * :switch:`-P{projname}` 4598 specifies the project defining the location of source files. When no 4599 file names are provided on the command line, all sources in the project 4600 are used as input. This switch is required. 4601 4602 * :switch:`{filename}` 4603 is the name of the source file containing the library unit package *declaration* 4604 (the package "spec") for which a test package will be created. The file name 4605 may be given with a path. 4606 4607 * :samp:`{switches}` 4608 is an optional sequence of switches as described below. 4609 4610 * :samp:`{gcc_switches}` 4611 is a list of additional switches for 4612 ``gcc`` that will be passed to all compiler invocations 4613 made by ``gnattest`` to generate a set of ASIS trees. 4614 4615 4616 ``gnattest`` results can be found in two different places. 4617 4618 * *automatic harness*: 4619 This is the harness code, which is located by default in 4620 "gnattest/harness" directory created in the object directory of 4621 the main project file. All of this code is generated completely 4622 automatically and can be destroyed and regenerated at will, with the 4623 exception of the file *gnattest_common.gpr*, which is created if absent, 4624 but never overwritten. It is not recommended to modify other files 4625 manually, since these modifications will be lost if ``gnattest`` is re-run. 4626 The entry point in the harness code is 4627 the project file named *test_driver.gpr*. Tests can be compiled and run 4628 using a command such as: 4629 4630 :: 4631 4632 $ gprbuild -P<harness-dir>/test_driver 4633 4634 Note that if you need to adjust any options used to compile the harness, 4635 you can do so by editing the file *gnattest_common.gpr*. 4636 4637 * *actual unit test skeletons*: 4638 A test skeleton for each visible subprogram is created in a separate file, if it 4639 doesn't exist already. By default, those separate test files are located in a 4640 "gnattest/tests" directory that is created in the object directory of 4641 corresponding project file. For example, if a source file my_unit.ads in 4642 directory src contains a visible subprogram Proc, then the corresponding unit 4643 test will be found in file src/tests/my_unit-test_data-tests.adb and will be 4644 called Test_Proc_<code>. <code> is a signature encoding used to differentiate 4645 test names in case of overloading. 4646 4647 Note that if the project already has both my_unit.ads and my_unit-test_data.ads, 4648 this will cause a name conflict with the generated test package. 4649 4650 4651 .. _Test_Execution_Mode: 4652 4653 Test Execution Mode 4654 ^^^^^^^^^^^^^^^^^^^ 4655 4656 In this mode ``gnattest`` has a the following command-line interface: 4657 4658 :: 4659 4660 $ gnattest test_drivers.list [ switches ] 4661 4662 where 4663 4664 * :samp:`{test_drivers.list}` 4665 is the name of the text file containing the list of executables to treat as 4666 test drivers. This file is automatically generated by gnattest, but can be 4667 hand-edited to add or remove tests. This switch is required. 4668 4669 4670 * :samp:`{switches}` 4671 is an optional sequence of switches as described below. 4672 4673 4674 .. _Switches_for_gnattest_in_framework_generation_mode: 4675 4676 Switches for ``gnattest`` in framework generation mode 4677 ------------------------------------------------------ 4678 4679 .. index:: --strict (gnattest) 4680 4681 :switch:`--strict` 4682 Return error exit code if there are any compilation errors. 4683 4684 .. index:: -q (gnattest) 4685 4686 :switch:`-q` 4687 Quiet mode: suppresses noncritical output messages. 4688 4689 4690 .. index:: -v (gnattest) 4691 4692 :switch:`-v` 4693 Verbose mode: produces additional output about the execution of the tool. 4694 When specified alone on the command line, prints tool version and exits. 4695 4696 4697 .. index:: -r (gnattest) 4698 4699 :switch:`-r` 4700 Recursively considers all sources from all projects. 4701 4702 .. index:: -files (gnattest) 4703 4704 :switch:`-files={filename}` 4705 Take as arguments the files listed in text file ``file``. 4706 Text file ``file`` may contain empty lines that are ignored. 4707 Each nonempty line should contain the name of an existing file. 4708 Several such switches may be specified simultaneously. 4709 4710 .. index:: --ignore (gnattest) 4711 4712 :switch:`--ignore={filename}` 4713 Do not process the sources listed in a specified file. 4714 4715 .. index:: --RTS (gnattest) 4716 4717 :switch:`--RTS={rts-path}` 4718 Specifies the default location of the runtime library. Same meaning as the 4719 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). For restricted 4720 profiles, ``gnattest`` takes into account the run-time limitations when 4721 generating the harness. 4722 4723 4724 .. index:: --additional-tests (gnattest) 4725 4726 :switch:`--additional-tests={projname}` 4727 Sources described in ``projname`` are considered potential additional 4728 manual tests to be added to the test suite. 4729 4730 4731 .. index:: --harness-only (gnattest) 4732 4733 :switch:`--harness-only` 4734 When this option is given, ``gnattest`` creates a harness for all 4735 sources, treating them as test packages. This option is not compatible with 4736 closure computation done by -U main. 4737 4738 4739 .. index:: --separate-drivers (gnattest) 4740 4741 :switch:`--separate-drivers[={val}]` 4742 Generates a separate test driver for each test or unit under test, rather 4743 than a single executable incorporating all tests. ``val`` can be "unit" or 4744 "test", or may be omitted, which defaults to "unit". 4745 4746 4747 .. index:: --stub (gnattest) 4748 4749 :switch:`--stub` 4750 Generates the testing framework that uses subsystem stubbing to isolate the 4751 code under test. 4752 4753 4754 .. index:: --harness-dir (gnattest) 4755 4756 :switch:`--harness-dir={dirname}` 4757 Specifies the directory that will hold the harness packages and project file 4758 for the test driver. If the ``dirname`` is a relative path, it is considered 4759 relative to the object directory of the project file. 4760 4761 4762 .. index:: --tests-dir (gnattest) 4763 4764 :switch:`--tests-dir={dirname}` 4765 All test packages are placed in the ``dirname`` directory. 4766 If the ``dirname`` is a relative path, it is considered relative to the object 4767 directory of the project file. When all sources from all projects are taken 4768 recursively from all projects, ``dirname`` directories are created for each 4769 project in their object directories and test packages are placed accordingly. 4770 4771 4772 .. index:: --subdir (gnattest) 4773 4774 :switch:`--subdir={dirname}` 4775 Test packages are placed in a subdirectory of the corresponding source 4776 directory, with the name ``dirname``. Thus, each set of unit tests is located 4777 in a subdirectory of the code under test. If the sources are in separate 4778 directories, each source directory has a test subdirectory named ``dirname``. 4779 4780 4781 .. index:: --tests-root (gnattest) 4782 4783 :switch:`--tests-root={dirname}` 4784 The hierarchy of source directories, if any, is recreated in the ``dirname`` 4785 directory, with test packages placed in directories corresponding to those 4786 of the sources. 4787 If the ``dirname`` is a relative path, it is considered relative to the object 4788 directory of the project file. When projects are considered recursively, 4789 directory hierarchies of tested sources are 4790 recreated for each project in their object directories and test packages are 4791 placed accordingly. 4792 4793 4794 .. index:: --stubs-dir (gnattest) 4795 4796 :switch:`--stubs-dir={dirname}` 4797 The hierarchy of directories containing stubbed units is recreated in 4798 the ``dirname`` directory, with stubs placed in directories corresponding to 4799 projects they are derived from. 4800 If the ``dirname`` is a relative path, it is considered relative to the object 4801 directory of the project file. When projects are considered recursively, 4802 directory hierarchies of stubs are 4803 recreated for each project in their object directories and test packages are 4804 placed accordingly. 4805 4806 4807 .. index:: --exclude-from-stubbing (gnattest) 4808 4809 :switch:`--exclude-from-stubbing={filename}` 4810 Disables stubbing of units listed in ``filename``. The file should contain 4811 corresponding spec files, one per line. 4812 4813 :switch:`--exclude-from-stubbing:{unit}={filename}` 4814 Same as above, but corresponding units will not be stubbed only when testing 4815 specified ``unit``. 4816 4817 .. index:: --validate-type-extensions (gnattest) 4818 4819 :switch:`--validate-type-extensions` 4820 Enables substitution check: run all tests from all parents in order 4821 to check substitutability in accordance with the Liskov substitution principle (LSP). 4822 4823 .. index:: --inheritance-check (gnattest) 4824 4825 :switch:`--inheritance-check` 4826 Enables inheritance check: run inherited tests against descendants. 4827 4828 .. index:: --no-inheritance-check (gnattest) 4829 4830 :switch:`--no-inheritance-check` 4831 Disables inheritance check. 4832 4833 .. index:: --no-inheritance-check (gnattest) 4834 4835 :switch:`--test-case-only` 4836 Generates test skeletons only for subprograms that have at least one 4837 associated pragma or aspect Test_Case. 4838 4839 .. index:: --skeleton-default (gnattest) 4840 4841 :switch:`--skeleton-default={val}` 4842 Specifies the default behavior of generated skeletons. ``val`` can be either 4843 "fail" or "pass", "fail" being the default. 4844 4845 4846 .. index:: --passed-tests (gnattest) 4847 4848 :switch:`--passed-tests={val}` 4849 Specifies whether or not passed tests should be shown. ``val`` can be either 4850 "show" or "hide", "show" being the default. 4851 4852 4853 .. index:: --exit-status (gnattest) 4854 4855 :switch:`--exit-status={val}` 4856 Specifies whether or not generated test driver should return failure exit 4857 status if at least one test fails or crashes. ``val`` can be either 4858 "on" or "off", "off" being the default. 4859 4860 4861 .. index:: --omit-sloc (gnattest) 4862 4863 :switch:`--omit-sloc` 4864 Suppresses comment line containing file name and line number of corresponding 4865 subprograms in test skeletons. 4866 4867 4868 .. index:: --no-command-line (gnattest) 4869 4870 :switch:`--no-command-line` 4871 Don't add command line support to test driver. Note that regardless of this 4872 switch, ``gnattest`` will automatically refrain from adding command 4873 line support if it detects that the selected run-time doesn't provide 4874 this capability. 4875 4876 4877 .. index:: --separates (gnattest) 4878 4879 :switch:`--separates` 4880 Bodies of all test routines are generated as separates. Note that this mode is 4881 kept for compatibility reasons only and it is not advised to use it due to 4882 possible problems with hash in names of test skeletons when using an 4883 inconsistent casing. Separate test skeletons can be incorporated to monolith 4884 test package with improved hash being used by using ``--transition`` 4885 switch. 4886 4887 4888 .. index:: --transition (gnattest) 4889 4890 :switch:`--transition` 4891 This allows transition from separate test routines to monolith test packages. 4892 All matching test routines are overwritten with contents of corresponding 4893 separates. Note that if separate test routines had any manually added with 4894 clauses they will be moved to the test package body as is and have to be moved 4895 by hand. 4896 4897 4898 .. index:: --test-duration (gnattest) 4899 4900 :switch:`--test-duration` 4901 Adds time measurements for each test in generated test driver. 4902 4903 4904 :switch:`--tests_root`, :switch:`--subdir` and :switch:`--tests-dir` switches are mutually exclusive. 4905 4906 4907 .. _Switches_for_gnattest_in_test_execution_mode: 4908 4909 Switches for ``gnattest`` in test execution mode 4910 ------------------------------------------------ 4911 4912 4913 .. index:: --passed-tests (gnattest) 4914 4915 :switch:`--passed-tests={val}` 4916 Specifies whether or not passed tests should be shown. ``val`` can be either 4917 "show" or "hide", "show" being the default. 4918 4919 4920 .. index:: --queues (gnattest) 4921 .. index:: -j (gnattest) 4922 4923 :switch:`--queues={n}`, :switch:`-j{n}` 4924 Runs ``n`` tests in parallel (default is 1). 4925 4926 4927 .. index:: --copy-environment (gnattest) 4928 4929 :switch:`--copy-environment={dir}` 4930 Contents of ``dir`` directory will be copied to temporary directories 4931 created by gnattest in which individual test drivers are spawned. 4932 4933 4934 .. _Project_Attributes_for_gnattest: 4935 4936 Project Attributes for ``gnattest`` 4937 ----------------------------------- 4938 4939 Most of the command-line options can also be passed to the tool by adding 4940 special attributes to the project file. Those attributes should be put in 4941 package ``Gnattest``. Here is the list of attributes: 4942 4943 4944 * ``Tests_Root`` 4945 is used to select the same output mode as with the ``--tests-root`` option. 4946 This attribute cannot be used together with ``Subdir`` or ``Tests_Dir``. 4947 4948 * ``Subdir`` 4949 is used to select the same output mode as with the ``--subdir`` option. 4950 This attribute cannot be used together with ``Tests_Root`` or ``Tests_Dir``. 4951 4952 * ``Tests_Dir`` 4953 is used to select the same output mode as with the ``--tests-dir`` option. 4954 This attribute cannot be used together with ``Subdir`` or ``Tests_Root``. 4955 4956 * ``Stubs_Dir`` 4957 is used to select the same output mode as with the ``--stubs-dir`` option. 4958 4959 * ``Harness_Dir`` 4960 is used to specify the directory in which to place harness packages and project 4961 file for the test driver, otherwise specified by ``--harness-dir``. 4962 4963 * ``Additional_Tests`` 4964 is used to specify the project file, otherwise given by 4965 ``--additional-tests`` switch. 4966 4967 * ``Skeletons_Default`` 4968 is used to specify the default behaviour of test skeletons, otherwise 4969 specified by ``--skeleton-default`` option. The value of this attribute 4970 should be either ``pass`` or ``fail``. 4971 4972 * ``Default_Stub_Exclusion_List`` 4973 is used to specify the file with list of units whose bodies should not 4974 be stubbed, otherwise specified by ``--exclude-from-stubbing=filename``. 4975 4976 * ``Stub_Exclusion_List ("unit")`` 4977 is used to specify the file with list of units whose bodies should not 4978 be stubbed when testing "unit", otherwise specified by 4979 ``--exclude-from-stubbing:unit=filename``. 4980 4981 Each of those attributes can be overridden from the command line if needed. 4982 Other ``gnattest`` switches can also be passed via the project 4983 file as an attribute list called ``Gnattest_Switches``. 4984 4985 4986 .. _Simple_gnattest_Example: 4987 4988 Simple Example 4989 -------------- 4990 4991 Let's take a very simple example using the first ``gnattest`` example 4992 located in: 4993 4994 :: 4995 4996 <install_prefix>/share/examples/gnattest/simple 4997 4998 This project contains a simple package containing one subprogram. By running ``gnattest``: 4999 5000 :: 5001 5002 $ gnattest --harness-dir=driver -Psimple.gpr 5003 5004 a test driver is created in directory ``driver``. It can be compiled and run: 5005 5006 :: 5007 5008 $ cd obj/driver 5009 $ gprbuild -Ptest_driver 5010 $ test_runner 5011 5012 One failed test with the diagnosis "test not implemented" is reported. 5013 Since no special output option was specified, the test package ``Simple.Tests`` 5014 is located in: 5015 5016 :: 5017 5018 <install_prefix>/share/examples/gnattest/simple/obj/gnattest/tests 5019 5020 5021 For each package containing visible subprograms, a child test package is 5022 generated. It contains one test routine per tested subprogram. Each 5023 declaration of a test subprogram has a comment specifying which tested 5024 subprogram it corresponds to. Bodies of test routines are placed in test package 5025 bodies and are surrounded by special comment sections. Those comment sections 5026 should not be removed or modified in order for gnattest to be able to regenerate 5027 test packages and keep already written tests in place. 5028 The test routine ``Test_Inc_5eaee3`` located at :file:`simple-test_data-tests.adb` contains 5029 a single statement: a call to procedure ``Assert``. It has two arguments: 5030 the Boolean expression we want to check and the diagnosis message to display if 5031 the condition is false. 5032 5033 That is where actual testing code should be written after a proper setup. 5034 An actual check can be performed by replacing the ``Assert`` call with: 5035 5036 :: 5037 5038 Assert (Inc (1) = 2, "wrong incrementation"); 5039 5040 After recompiling and running the test driver, one successfully passed test 5041 is reported. 5042 5043 5044 .. _Setting_Up_and_Tearing_Down_the_Testing_Environment: 5045 5046 Setting Up and Tearing Down the Testing Environment 5047 --------------------------------------------------- 5048 5049 Besides test routines themselves, each test package has a parent package 5050 ``Test_Data`` that has two procedures: ``Set_Up`` and ``Tear_Down``. This package is never 5051 overwritten by the tool. ``Set_Up`` is called before each test routine of the 5052 package, and ``Tear_Down`` is called after each test routine. Those two procedures 5053 can be used to perform necessary initialization and finalization, 5054 memory allocation, etc. Test type declared in ``Test_Data`` package is parent type 5055 for the test type of test package and can have user-defined components whose 5056 values can be set by ``Set_Up`` routine and used in test routines afterwards. 5057 5058 5059 .. _Regenerating_Tests: 5060 5061 Regenerating Tests 5062 ------------------ 5063 5064 Bodies of test routines and ``Test_Data`` packages are never overridden after they 5065 have been created once. As long as the name of the subprogram, full expanded Ada 5066 names and order of its parameters are the same, and comment sections are 5067 intact, the old test routine will fit in its place and no test skeleton will be 5068 generated for the subprogram. 5069 5070 This can be demonstrated with the previous example. By uncommenting declaration 5071 and body of function Dec in ``simple.ads`` and ``simple.adb``, running 5072 ``gnattest`` on the project, and then running the test driver: 5073 5074 :: 5075 5076 $ gnattest --harness-dir=driver -Psimple.gpr 5077 $ cd obj/driver 5078 $ gprbuild -Ptest_driver 5079 $ test_runner 5080 5081 The old test is not replaced with a stub, nor is it lost, but a new test 5082 skeleton is created for function ``Dec``. 5083 5084 The only way of regenerating tests skeletons is to remove the previously created 5085 tests together with corresponding comment sections. 5086 5087 5088 .. _Default_Test_Behavior: 5089 5090 Default Test Behavior 5091 --------------------- 5092 5093 The generated test driver can treat unimplemented tests in two ways: 5094 either count them all as failed (this is useful to see which tests are still 5095 left to implement) or as passed (to sort out unimplemented ones from those 5096 actually failing). 5097 5098 The test driver accepts a switch to specify this behavior: 5099 :switch:`--skeleton-default={val}`, where ``val`` is either ``pass`` or ``fail`` (exactly as for 5100 ``gnattest``). 5101 5102 The default behavior of the test driver is set with the same switch 5103 as passed to ``gnattest`` when generating the test driver. 5104 5105 Passing it to the driver generated on the first example: 5106 5107 :: 5108 5109 $ test_runner --skeleton-default=pass 5110 5111 makes both tests pass, even the unimplemented one. 5112 5113 5114 .. _Testing_Primitive_Operations_of_Tagged_Types: 5115 5116 Testing Primitive Operations of Tagged Types 5117 -------------------------------------------- 5118 5119 Creation of test skeletons for primitive operations of tagged types entails 5120 a number of features. Test routines for all primitives of a given tagged type 5121 are placed in a separate child package named according to the tagged type. For 5122 example, if you have tagged type ``T`` in package ``P``, all tests for primitives 5123 of ``T`` will be in ``P.T_Test_Data.T_Tests``. 5124 5125 Consider running ``gnattest`` on the second example (note: actual tests for this 5126 example already exist, so there's no need to worry if the tool reports that 5127 no new stubs were generated): 5128 5129 :: 5130 5131 $ cd <install_prefix>/share/examples/gnattest/tagged_rec 5132 $ gnattest --harness-dir=driver -Ptagged_rec.gpr 5133 5134 Taking a closer look at the test type declared in the test package 5135 *Speed1.Controller_Test_Data* is necessary. It is declared in: 5136 5137 :: 5138 5139 <install_prefix>/share/examples/gnattest/tagged_rec/obj/gnattest/tests 5140 5141 Test types are direct or indirect descendants of 5142 *AUnit.Test_Fixtures.Test_Fixture* type. In the case of non-primitive tested 5143 subprograms, the user doesn't need to be concerned with them. However, 5144 when generating test packages for primitive operations, there are some things 5145 the user needs to know. 5146 5147 Type ``Test_Controller`` has components that allow assignment of various 5148 derivations of type ``Controller``. And if you look at the specification of 5149 package *Speed2.Auto_Controller*, you will see that ``Test_Auto_Controller`` 5150 actually derives from ``Test_Controller`` rather than AUnit type ``Test_Fixture``. 5151 Thus, test types mirror the hierarchy of tested types. 5152 5153 The ``Set_Up`` procedure of ``Test_Data`` package corresponding to a test package 5154 of primitive operations of type ``T`` assigns to ``Fixture`` a reference to an 5155 object of that exact type ``T``. Note, however, that if the tagged type has 5156 discriminants, the ``Set_Up`` only has a commented template for setting 5157 up the fixture, since filling the discriminant with actual value is up 5158 to the user. 5159 5160 The knowledge of the structure of test types allows additional testing 5161 without additional effort. Those possibilities are described below. 5162 5163 5164 .. _Testing_Inheritance: 5165 5166 Testing Inheritance 5167 ------------------- 5168 5169 Since the test type hierarchy mimics the hierarchy of tested types, the 5170 inheritance of tests takes place. An example of such inheritance can be 5171 seen by running the test driver generated for the second example. As previously 5172 mentioned, actual tests are already written for this example. 5173 5174 :: 5175 5176 $ cd obj/driver 5177 $ gprbuild -Ptest_driver 5178 $ test_runner 5179 5180 There are 6 passed tests while there are only 5 testable subprograms. The test 5181 routine for function Speed has been inherited and run against objects of the 5182 derived type. 5183 5184 5185 .. _Tagged_Type_Substitutability_Testing: 5186 5187 Tagged Type Substitutability Testing 5188 ------------------------------------ 5189 5190 *Tagged Type Substitutability Testing* is a way of verifying the global type 5191 consistency by testing. Global type consistency is a principle stating that if 5192 ``S`` is a subtype of ``T`` (in Ada, ``S`` is a derived type of tagged type ``T``), 5193 then objects of type ``T`` may be replaced with objects of type ``S`` (that is, 5194 objects of type ``S`` may be substituted for objects of type ``T``), without 5195 altering any of the desirable properties of the program. When the properties 5196 of the program are expressed in the form of subprogram preconditions and 5197 postconditions (let's call them pre and post), the principle is formulated as 5198 relations between the pre and post of primitive operations and the pre and post 5199 of their derived operations. The pre of a derived operation should not be 5200 stronger than the original pre, and the post of the derived operation should 5201 not be weaker than the original post. Those relations ensure that verifying if 5202 a dispatching call is safe can be done just by using the pre and post of the 5203 root operation. 5204 5205 Verifying global type consistency by testing consists of running all the unit 5206 tests associated with the primitives of a given tagged type with objects of its 5207 derived types. 5208 5209 In the example used in the previous section, there was clearly a violation of 5210 type consistency. The overriding primitive ``Adjust_Speed`` in package ``Speed2`` 5211 removes the functionality of the overridden primitive and thus doesn't respect 5212 the consistency principle. 5213 ``gnattest`` has a special option to run overridden parent tests against objects 5214 of the type which have overriding primitives: 5215 5216 :: 5217 5218 $ gnattest --harness-dir=driver --validate-type-extensions -Ptagged_rec.gpr 5219 $ cd obj/driver 5220 $ gprbuild -Ptest_driver 5221 $ test_runner 5222 5223 While all the tests pass by themselves, the parent test for ``Adjust_Speed`` fails 5224 against objects of the derived type. 5225 5226 Non-overridden tests are already inherited for derived test types, so the 5227 ``--validate-type-extensions`` enables the application of overridden tests 5228 to objects of derived types. 5229 5230 5231 .. _Testing_with_Contracts: 5232 5233 Testing with Contracts 5234 ---------------------- 5235 5236 ``gnattest`` supports pragmas ``Pre``, ``Post``, and ``Test_Case``, 5237 as well as the corresponding Ada 2012 aspects. 5238 Test routines are generated, one per each ``Test_Case`` associated with a tested 5239 subprogram. Those test routines have special wrappers for tested functions 5240 that have composition of pre- and postcondition of the subprogram with 5241 "requires" and "ensures" of the ``Test_Case`` (depending on the mode, pre and post 5242 either count for ``Nominal`` mode or do *not* count for ``Robustness`` mode). 5243 5244 The third example demonstrates how this works: 5245 5246 :: 5247 5248 $ cd <install_prefix>/share/examples/gnattest/contracts 5249 $ gnattest --harness-dir=driver -Pcontracts.gpr 5250 5251 Putting actual checks within the range of the contract does not cause any 5252 error reports. For example, for the test routine which corresponds to 5253 test case 1: 5254 5255 :: 5256 5257 Assert (Sqrt (9.0) = 3.0, "wrong sqrt"); 5258 5259 and for the test routine corresponding to test case 2: 5260 5261 :: 5262 5263 Assert (Sqrt (-5.0) = -1.0, "wrong error indication"); 5264 5265 are acceptable: 5266 5267 :: 5268 5269 $ cd obj/driver 5270 $ gprbuild -Ptest_driver 5271 $ test_runner 5272 5273 However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get 5274 a precondition violation for test case one. Also, by using any otherwise 5275 correct but positive pair of numbers in the second test routine, you can also 5276 get a precondition violation. Postconditions are checked and reported 5277 the same way. 5278 5279 5280 .. _Additional_Tests: 5281 5282 Additional Tests 5283 ---------------- 5284 5285 ``gnattest`` can add user-written tests to the main suite of the test 5286 driver. ``gnattest`` traverses the given packages and searches for test 5287 routines. All procedures with a single in out parameter of a type which is 5288 derived from *AUnit.Test_Fixtures.Test_Fixture* and that are declared in package 5289 specifications are added to the suites and are then executed by the test driver. 5290 (``Set_Up`` and ``Tear_Down`` are filtered out.) 5291 5292 An example illustrates two ways of creating test harnesses for user-written 5293 tests. Directory ``additional_tests`` contains an AUnit-based test driver written 5294 by hand. 5295 5296 :: 5297 5298 <install_prefix>/share/examples/gnattest/additional_tests/ 5299 5300 To create a test driver for already-written tests, use the ``--harness-only`` 5301 option: 5302 5303 :: 5304 5305 gnattest -Padditional/harness/harness.gpr --harness-dir=harness_only \\ 5306 --harness-only 5307 gprbuild -Pharness_only/test_driver.gpr 5308 harness_only/test_runner 5309 5310 Additional tests can also be executed together with generated tests: 5311 5312 :: 5313 5314 gnattest -Psimple.gpr --additional-tests=additional/harness/harness.gpr \\ 5315 --harness-dir=mixing 5316 gprbuild -Pmixing/test_driver.gpr 5317 mixing/test_runner 5318 5319 5320 .. _Individual_Test_Drivers: 5321 5322 Individual Test Drivers 5323 ----------------------- 5324 5325 By default, ``gnattest`` generates a monolithic test driver that 5326 aggregates the individual tests into a single executable. It is also possible 5327 to generate separate executables for each test or each unit under test, by 5328 passing the switch ``--separate-drivers`` with corresponding parameter. This 5329 approach scales better for large testing campaigns, especially involving target 5330 architectures with limited resources typical for embedded development. It can 5331 also provide a major performance benefit on multi-core systems by allowing 5332 simultaneous execution of multiple tests. 5333 5334 ``gnattest`` can take charge of executing the individual tests; for this, 5335 instead of passing a project file, a text file containing the list of 5336 executables can be passed. Such a file is automatically generated by gnattest 5337 under the name :file:`test_drivers.list`, but it can be 5338 hand-edited to add or remove tests, or replaced. The individual tests can 5339 also be executed standalone, or from any user-defined scripted framework. 5340 5341 5342 .. _Stubbing: 5343 5344 Stubbing 5345 -------- 5346 5347 Depending on the testing campaign, it is sometimes necessary to isolate the 5348 part of the algorithm under test from its dependencies. This is accomplished 5349 via *stubbing*, i.e. replacing the subprograms that are called from the 5350 subprogram under test by stand-in subprograms that match the profiles of the 5351 original ones, but simply return predetermined values required by the test 5352 scenario. 5353 5354 This mode of test harness generation is activated by the switch ``--stub``. 5355 5356 The implementation approach chosen by ``gnattest`` is as follows. 5357 For each package under consideration all the packages it is directly depending 5358 on are stubbed, excluding the generic packages and package instantiations. 5359 The stubs are shared for each package under test. The specs of packages to stub 5360 remain intact, while their bodies are replaced, and hide the original bodies by 5361 means of extending projects. Also, for each stubbed 5362 package, a child package with setter routines for each subprogram declaration 5363 is created. These setters are meant to be used to set the behavior of 5364 stubbed subprograms from within test cases. 5365 5366 Note that subprograms belonging to the same package as the subprogram under 5367 test are not stubbed. This guarantees that the sources being tested are 5368 exactly the sources used for production, which is an important property for 5369 establishing the traceability between the testing campaign and production code. 5370 5371 Due to the nature of stubbing process, this mode implies the switch 5372 ``--separate-drivers``, i.e. an individual test driver (with the 5373 corresponding hierarchy of extending projects) is generated for each unit under 5374 test. 5375 5376 .. note:: 5377 5378 Developing a stubs-based testing campaign requires 5379 good understanding of the infrastructure created by ``gnattest`` for 5380 this purpose. We recommend following the two stubbing tutorials 5381 ``simple_stubbing`` and ``advanced_stubbing`` provided 5382 under :file:`<install_prefix>/share/examples/gnattest` before 5383 attempting to use this powerful feature. 5384 5385 5386 .. _Gnatcov_Integration: 5387 5388 Integration with GNATcoverage 5389 ----------------------------- 5390 5391 In addition to the harness, ``gnattest`` generates a Makefile. This Makefile 5392 provides targets for building the test drivers and also the targets for 5393 computing the coverage information using GNATcoverage framework when this 5394 coverage analysis tool is available. The target ``coverage`` fully automates 5395 the process: it will first build all test drivers, then run them under 5396 GNATcoverage, analyze individual trace files, and finally aggregate them: 5397 5398 :: 5399 5400 make coverage 5401 5402 GNATcoverage options, such as coverage criteria and generated report format, 5403 can be adjusted using Makefile variables provided for this purpose. 5404 5405 Note that coverage targets are not generated in the Makefile when 5406 --separate-drivers=test is passed to gnattest. 5407 5408 5409 .. _Putting_Tests_under_Version_Control: 5410 5411 Putting Tests under Version Control 5412 ----------------------------------- 5413 5414 As has been stated earlier, ``gnattest`` generates two different types 5415 of code, test skeletons and harness. The harness is generated completely 5416 automatically each time, does not require manual changes and therefore should 5417 not be put under version control. 5418 It makes sense to put under version control files containing test data packages, 5419 both specs and bodies, and files containing bodies of test packages. Note that 5420 test package specs are also generated automatically each time and should not be 5421 put under version control. 5422 Option ``--omit-sloc`` may be useful when putting test packages under version control. 5423 5424 5425 .. _Current_Limitations: 5426 5427 Current Limitations 5428 ------------------- 5429 5430 The tool currently has the following limitations: 5431 5432 * generic tests for nested generic packages and their instantiations are 5433 not supported; 5434 * tests for protected subprograms and entries are not supported; 5435 * pragma ``No_Run_Time`` is not supported; 5436 * pragma ``No_Secondary_Stack`` is not supported; 5437 * if pragmas for interfacing with foreign languages are used, manual 5438 adjustments might be necessary to make the test harness compilable; 5439 * use of some constructs, such as elaboration-control pragmas, Type_Invariant 5440 aspects, and complex variable initializations that use Subprogram'Access, 5441 may result in elaboration circularities in the generated harness. 5442 5443 5444.. only:: PRO or GPL 5445 5446 .. _The_Backtrace_Symbolizer_gnatsymbolize: 5447 5448 Translating Code Addresses into Source Locations with ``gnatsymbolize`` 5449 ======================================================================= 5450 5451 .. index:: ! gnatsymbolize 5452 5453 ``gnatsymbolize`` is a program which translates addresses into 5454 their corresponding filename, line number, and function names. 5455 5456 Running ``gnatsymbolize`` 5457 ------------------------- 5458 5459 :: 5460 5461 $ gnatsymbolize [ switches ] filename [ addresses ] 5462 5463 For instance, consider the following Ada program: 5464 5465 .. code-block:: ada 5466 5467 package Pck is 5468 Global_Val : Integer := 0; 5469 procedure Call_Me_First; 5470 end Pck; 5471 5472 with GNAT.IO; use GNAT.IO; 5473 with GNAT.Traceback; use GNAT.Traceback; 5474 with GNAT.Debug_Utilities; 5475 package body Pck is 5476 procedure Call_Me_Third is 5477 TB : Tracebacks_Array (1 .. 5); 5478 TB_len : Natural; 5479 begin 5480 Global_Val := Global_Val + 1; 5481 5482 Call_Chain (TB, TB_Len); 5483 for K in 1 .. TB_Len loop 5484 Put_Line (GNAT.Debug_Utilities.Image_C (TB (K))); 5485 end loop; 5486 end Call_Me_Third; 5487 5488 procedure Call_Me_Second is 5489 begin 5490 Call_Me_Third; 5491 end Call_Me_Second; 5492 5493 procedure Call_Me_First is 5494 begin 5495 Call_Me_Second; 5496 end Call_Me_First; 5497 end Pck; 5498 with Pck; use Pck; 5499 5500 procedure Foo is 5501 begin 5502 Global_Val := 123; 5503 Call_Me_First; 5504 end Foo; 5505 5506 This program, when built and run, prints a list of addresses which 5507 correspond to the traceback when inside function ``Call_Me_Third``. 5508 For instance, on x86_64 GNU/Linux: 5509 5510 :: 5511 5512 $ gnatmake -g -q foo.adb 5513 $ ./foo 5514 0x0000000000402561 5515 0x00000000004025EF 5516 0x00000000004025FB 5517 0x0000000000402611 5518 0x00000000004024C7 5519 5520 ``gnatsymbolize`` can be used to translate those addresses into 5521 code locations as follow: 5522 5523 :: 5524 5525 $ gnatsymbolize foo 0x0000000000402561 0x00000000004025EF \ 5526 0x00000000004025FB 0x0000000000402611 0x00000000004024C7 5527 Pck.Call_Me_Third at pck.adb:12 5528 Pck.Call_Me_Second at pck.adb:20 5529 Pck.Call_Me_First at pck.adb:25 5530 Foo at foo.adb:6 5531 Main at b~foo.adb:184 5532 5533 Switches for ``gnatsymbolize`` 5534 ------------------------------ 5535 5536 ``gnatsymbolize`` recognizes the following switches: 5537 5538 .. index:: --help (gnatsymbolize) 5539 5540 :switch:`--help` 5541 Display the program's usage, and then exit, disregarding all other 5542 options. 5543 5544 :switch:`--cache` 5545 Read the symbolic information from the executable and cache them 5546 in memory in order to accelerate the translation of each address 5547 into a symbolic location. 5548 5549 Depending on the size of the executable and the number of addresses 5550 to translate, this may not always make ``gnatsymbolize`` faster 5551 overall. 5552 5553 :switch:`--dump` 5554 If :switch:`--cache` is used, dump the contents of the cache on 5555 Standard Output. Has no effect otherwise. 5556 5557 :switch:`--count={N}` 5558 If specified, compute the symbolic traceback ``N`` times in a row. 5559 This option is mostly useful for measuring the performance of 5560 ``gnatsymbolize``, particularly in the case where the cache is 5561 being used. 5562 5563 Requirements for Correct Operation 5564 ---------------------------------- 5565 5566 The translation is performed by reading the DWARF debugging 5567 information produced by the compiler for each unit. All units 5568 for which the translation is to be done must therefore be compiled 5569 such that DWARF debugging information is produced. In most cases, 5570 this is done by simply compiling with ``-g``. 5571 5572 This program provides a functionality similar to ``addr2line``. 5573 It has fewer options to tailor its output, but has been designed 5574 to require fewer of the DWARF sections to be present in the 5575 executable. In particular, the following sections can be 5576 stripped from the executable without impact to ``gnatsymbolize``'s 5577 functionality: 5578 5579 * ``.debug_str`` 5580 * ``.debug_ranges`` 5581 5582 5583.. only:: PRO or GPL 5584 5585 .. _Using_Project_Files_with_GNAT_Tools: 5586 5587 Using Project Files with GNAT Tools 5588 =================================== 5589 5590 This section describes how project files can be used in conjunction 5591 with a number of GNAT tools. 5592 For a comprehensive description of project files and the overall 5593 GNAT Project Manager facility, please refer to the 5594 *GNAT Project Manager* chapter in the 5595 *GPRbuild and GPR Companion Tools User's Guide*. 5596 5597 .. index:: Project-aware tool 5598 5599 If a tool can take a project file as an option and extract the needed 5600 information, such a tool is called a *project-aware* tool. 5601 5602 .. _Switches_Related_to_Project_Files: 5603 5604 Switches Related to Project Files 5605 --------------------------------- 5606 5607 The following switches are used by the project-aware GNAT tools: 5608 5609 :switch:`-P{project_file}` 5610 Indicates the name of the project file whose source files are to 5611 be processed. The exact set of sources depends on other options 5612 specified, see below. 5613 5614 :switch:`-U` 5615 If a project file is supplied, say for project ``proj``, 5616 but no sources are specified for ``proj`` (either by a 5617 project attribute or through a tool option that provides a list 5618 of the files to be used), process all the source files 5619 from projects imported either directly or indirectly by ``proj``. 5620 Otherwise this option has no effect. 5621 5622 :switch:`-U {source_file}` 5623 Similar to :switch:`-U`, but if no sources are specified then 5624 process only those source files for units in the closure of 5625 the Ada source contained in ``source_file``. Note that this option 5626 expects the source file name but not the Ada unit name as its 5627 parameter. 5628 5629 :switch:`-X{name}={val}` 5630 Indicates that the external variable ``name`` in the project has the 5631 value ``val``. Has no effect if no project has been specified. 5632 5633 :switch:`--subdirs={dir}` 5634 Use the ``dir`` subdirectory of the project's object directory (or the ``dir`` 5635 subdirectory of the project file directory if the project does not specify 5636 an object directory) for tool output files. Has no effect if no project 5637 has been specified or if :switch:`--no_objects_dir` is specified. 5638 5639 :switch:`--no_objects_dir` 5640 Place all the result files into the current directory (i.e., the directory 5641 from which the tool invocation command is issued) instead of the project's 5642 object directory. Has no effect if no project has been specified. 5643 5644 :switch:`-eL` 5645 Follow all symbolic links when processing project files. 5646 5647 If a project file is specified and there is neither a :switch:`-U` option, 5648 nor a :switch:`-U {main_unit}` option, nor some other explicit option to 5649 specify the source files, then the sources to be processed are the 5650 immediate sources of the specified project (i.e., the source files directly 5651 defined by that project, either implicitly by residing in the project 5652 source directories, or explicitly through any of the source-related 5653 attributes). 5654 5655 .. _Tool-specific_packages_in_project files: 5656 5657 Tool-specific packages in project files 5658 --------------------------------------- 5659 5660 Each project-aware tool may have a corresponding package in a project file; 5661 the package names are given elsewhere in this manual, in the sections that describe 5662 the respective tools. 5663 5664 A tool-specific package in a project file may define the ``Default_Switches`` 5665 attribute indexed by "ada" (as language name). The value of this attribute 5666 is a list of switches that will be supplied at tool invocation. 5667 Project-specific switches cannot be specified through this attribute. 5668