3 .. |rightarrow| unicode:: 0x2192
5 .. _GNAT_Utility_Programs:
11 This chapter describes a number of utility programs:
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`
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`
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`
37 Other GNAT utilities are described elsewhere in this manual:
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`
45 .. _The_File_Cleanup_Utility_gnatclean:
47 The File Cleanup Utility ``gnatclean``
48 ======================================
50 .. index:: File cleanup tool
53 ``gnatclean`` is a tool that allows the deletion of files produced by the
54 compiler, binder and linker, including ALI files, object files, tree files,
55 expanded source files, library files, interface copy source files, binder
56 generated files and executable files.
58 .. _Running_gnatclean:
63 The ``gnatclean`` command has the form:
67 $ gnatclean switches names
69 where ``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.
73 In normal mode, ``gnatclean`` delete the files produced by the compiler and,
74 if switch :switch:`-c` is not specified, by the binder and
75 the linker. In informative-only mode, specified by switch
76 :switch:`-n`, the list of files that would have been deleted in
77 normal mode is listed, but no file is actually deleted.
80 .. _Switches_for_gnatclean:
82 Switches for ``gnatclean``
83 --------------------------
85 ``gnatclean`` recognizes the following switches:
87 .. index:: --version (gnatclean)
90 Display copyright and version, then exit disregarding all other options.
92 .. index:: --help (gnatclean)
95 If :switch:`--version` was not used, display usage, then exit disregarding
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.
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
107 .. index:: -c (gnatclean)
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.
114 .. index:: -D (gnatclean)
117 Indicate that ALI and object files should normally be found in directory ``dir``.
119 .. index:: -F (gnatclean)
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.
127 .. index:: -h (gnatclean)
130 Output a message explaining the usage of ``gnatclean``.
132 .. index:: -n (gnatclean)
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.
138 .. index:: -P (gnatclean)
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
147 .. index:: -q (gnatclean)
150 Quiet output. If there are no errors, do not output anything, except in
151 verbose mode (switch -v) or in informative-only mode
154 .. index:: -r (gnatclean)
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.
162 .. index:: -v (gnatclean)
167 .. index:: -vP (gnatclean)
170 Indicates the verbosity of the parsing of GNAT project files.
171 :ref:`Switches_Related_to_Project_Files`.
173 .. index:: -X (gnatclean)
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`.
181 .. index:: -aO (gnatclean)
184 When searching for ALI and object files, look in directory ``dir``.
186 .. index:: -I (gnatclean)
189 Equivalent to :switch:`-aO{dir}`.
191 .. index:: -I- (gnatclean)
193 .. index:: Source files, suppressing search
196 Do not look for ALI or object files in the directory
197 where ``gnatclean`` was invoked.
201 .. _The_GNAT_Library_Browser_gnatls:
203 The GNAT Library Browser ``gnatls``
204 ===================================
206 .. index:: Library browser
209 ``gnatls`` is a tool that outputs information about compiled
210 units. It gives the relationship between objects, unit names and source
211 files. It can also be used to check the source dependencies of a unit
212 as well as various characteristics.
219 The ``gnatls`` command has the form
223 $ gnatls switches object_or_ali_file
225 The main argument is the list of object or :file:`ali` files
226 (see :ref:`The_Ada_Library_Information_Files`)
227 for which information is requested.
229 In normal mode, without additional option, ``gnatls`` produces a
230 four-column listing. Each line represents information for a specific
231 object. The first column gives the full path of the object, the second
232 column gives the name of the principal unit in this object, the third
233 column gives the status of the source and the fourth column gives the
234 full path of the source representing this unit.
235 Here is a simple example of use:
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
250 The first line can be interpreted as follows: the main unit which is
252 object file :file:`demo1.o` is demo1, whose main source is in
253 :file:`demo1.adb`. Furthermore, the version of the source used for the
254 compilation of demo1 has been modified (DIF). Each source file has a status
255 qualifier which can be:
258 The version of the source file used for the compilation of the
259 specified unit corresponds exactly to the actual source file.
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.
269 No version of the source found on the path corresponds to the source
270 used to build this object.
272 *??? (file not found)*
273 No source file was found for this unit.
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.
281 .. _Switches_for_gnatls:
283 Switches for ``gnatls``
284 -----------------------
286 ``gnatls`` recognizes the following switches:
289 .. index:: --version (gnatls)
292 Display copyright and version, then exit disregarding all other options.
295 .. index:: --help (gnatls)
298 If :switch:`--version` was not used, display usage, then exit disregarding
302 .. index:: -a (gnatls)
305 Consider all units, including those of the predefined Ada library.
306 Especially useful with :switch:`-d`.
309 .. index:: -d (gnatls)
312 List sources from which specified units depend on.
315 .. index:: -h (gnatls)
318 Output the list of options.
321 .. index:: -o (gnatls)
324 Only output information about object files.
327 .. index:: -s (gnatls)
330 Only output information about source files.
333 .. index:: -u (gnatls)
336 Only output information about compilation units.
339 .. index:: -files (gnatls)
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.
348 .. index:: -aO (gnatls)
350 .. index:: -aI (gnatls)
352 .. index:: -I (gnatls)
354 .. index:: -I- (gnatls)
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`).
361 .. index:: -aP (gnatls)
364 Add ``dir`` at the beginning of the project search dir.
367 .. index:: --RTS (gnatls)
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`).
374 .. index:: -v (gnatls)
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:
382 * *Preelaborable*: The unit is preelaborable in the Ada sense.
384 * *No_Elab_Code*: No elaboration code has been produced by the compiler for this unit.
386 * *Pure*: The unit is pure in the Ada sense.
388 * *Elaborate_Body*: The unit contains a pragma Elaborate_Body.
390 * *Remote_Types*: The unit contains a pragma Remote_Types.
392 * *Shared_Passive*: The unit contains a pragma Shared_Passive.
394 * *Predefined*: This unit is part of the predefined environment and cannot be modified
397 * *Remote_Call_Interface*: The unit contains a pragma Remote_Call_Interface.
400 .. _Example_of_gnatls_Usage:
402 Example of ``gnatls`` Usage
403 ---------------------------
405 Example of using the verbose switch. Note how the source and
406 object paths are affected by the -I switch.
410 $ gnatls -v -I.. demo1.o
412 GNATLS 5.03w (20041123-34)
413 Copyright 1997-2004 Free Software Foundation, Inc.
418 /home/comar/local/adainclude/
423 /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
427 /home/comar/local/lib/gnat/
432 Kind => subprogram body
433 Flags => No_Elab_Code
434 Source => demo1.adb modified
436 The following is an example of use of the dependency list.
437 Note the use of the -s switch
438 which gives a straight list of source files. This can be useful for
439 building specialized scripts.
444 ./demo2.o demo2 OK demo2.adb
450 $ gnatls -d -s -a demo1.o
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
459 /home/comar/local/adainclude/gnat.ads
460 /home/comar/local/adainclude/g-io.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
475 .. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind:
477 The Cross-Referencing Tools ``gnatxref`` and ``gnatfind``
478 =========================================================
480 .. index:: ! gnatxref
481 .. index:: ! gnatfind
483 The compiler generates cross-referencing information (unless
484 you set the :switch:`-gnatx` switch), which are saved in the :file:`.ali` files.
485 This information indicates where in the source each entity is declared and
486 referenced. Note that entities in package Standard are not included, but
487 entities in all other predefined units are included in the output.
489 Before using any of these two tools, you need to compile successfully your
490 application, so that GNAT gets a chance to generate the cross-referencing
493 The two tools ``gnatxref`` and ``gnatfind`` take advantage of this
494 information to provide the user with the capability to easily locate the
495 declaration and references to an entity. These tools are quite similar,
496 the difference being that ``gnatfind`` is intended for locating
497 definitions and/or references to a specified entity or entities, whereas
498 ``gnatxref`` is oriented to generating a full report of all
501 To 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
504 information will not be generated.
506 .. _gnatxref_Switches:
508 ``gnatxref`` Switches
509 ---------------------
511 The command invocation for ``gnatxref`` is:
515 $ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
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.
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
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.
532 The following switches are available for ``gnatxref``:
535 .. index:: --version (gnatxref)
538 Display copyright and version, then exit disregarding all other options.
541 .. index:: --help (gnatxref)
544 If :switch:`--version` was not used, display usage, then exit disregarding
548 .. index:: -a (gnatxref)
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.
559 .. index:: -aIDIR (gnatxref)
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``.
566 .. index:: -aODIR (gnatxref)
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
574 .. index:: -nostdinc (gnatxref)
577 Do not look for sources in the system default directory.
580 .. index:: -nostdlib (gnatxref)
583 Do not look for library files in the system default directory.
586 .. index:: --ext (gnatxref)
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
595 .. index:: --RTS (gnatxref)
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`).
602 .. index:: -d (gnatxref)
605 If this switch is set ``gnatxref`` will output the parent type
606 reference for each matching derived types.
609 .. index:: -f (gnatxref)
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.
617 .. index:: -g (gnatxref)
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``.
625 .. index:: -IDIR (gnatxref)
628 Equivalent to :switch:`-aODIR -aIDIR`.
631 .. index:: -pFILE (gnatxref)
634 Specify a configuration file to use to list the source and object directories.
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`.
640 See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
641 of this configuration file.
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.
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.
654 All these switches may be in any order on the command line, and may even
655 appear after the file names. They need not be separated by spaces, thus
656 you can say ``gnatxref -ag`` instead of ``gnatxref -a -g``.
658 .. _gnatfind_Switches:
660 ``gnatfind`` Switches
661 ---------------------
663 The command invocation for ``gnatfind`` is:
667 $ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
670 with the following iterpretation of the command arguments:
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`.
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.
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.
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`
691 A decimal integer identifying the line number containing
692 the reference to the entity (or entities) to be located.
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.
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.
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
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.
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.
719 At least one of 'sourcefile' or 'pattern' has to be present on
722 The following switches are available:
724 .. index:: --version (gnatfind)
727 Display copyright and version, then exit disregarding all other options.
730 .. index:: --help (gnatfind)
733 If :switch:`--version` was not used, display usage, then exit disregarding
737 .. index:: -a (gnatfind)
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.
748 .. index:: -aIDIR (gnatfind)
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``.
755 .. index:: -aODIR (gnatfind)
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
763 .. index:: -nostdinc (gnatfind)
766 Do not look for sources in the system default directory.
769 .. index:: -nostdlib (gnatfind)
772 Do not look for library files in the system default directory.
775 .. index:: --ext (gnatfind)
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.
783 .. index:: --RTS (gnatfind)
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`).
790 .. index:: -d (gnatfind)
793 If this switch is set, then ``gnatfind`` will output the parent type
794 reference for each matching derived types.
797 .. index:: -e (gnatfind)
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.
805 .. index:: -f (gnatfind)
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.
813 .. index:: -g (gnatfind)
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``.
821 .. index:: -IDIR (gnatfind)
824 Equivalent to :switch:`-aODIR -aIDIR`.
827 .. index:: -pFILE (gnatfind)
830 Specify a configuration file to use to list the source and object directories.
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`.
836 See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
837 of this configuration file.
839 .. index:: -r (gnatfind)
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).
849 .. index:: -s (gnatfind)
852 If this switch is set, then ``gnatfind`` will output the content
853 of the Ada source file lines were the entity was found.
856 .. index:: -t (gnatfind)
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.
865 All these switches may be in any order on the command line, and may even
866 appear after the file names. They need not be separated by spaces, thus
867 you can say ``gnatxref -ag`` instead of
870 As stated previously, ``gnatfind`` will search in every directory in the
871 search path. You can force it to look only in the current directory if
872 you specify ``*`` at the end of the command line.
874 .. _Configuration_Files_for_gnatxref_and_gnatfind:
876 Configuration Files for ``gnatxref`` and ``gnatfind``
877 -----------------------------------------------------
879 Configuration files are used by ``gnatxref`` and ``gnatfind`` to specify
880 the list of source and object directories to consider. They can be
881 specified via the :switch:`-p` switch.
883 The following lines can be included, in any order in the file:
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
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
897 Any other line will be silently ignored.
899 .. _Regular_Expressions_in_gnatfind_and_gnatxref:
901 Regular Expressions in ``gnatfind`` and ``gnatxref``
902 ----------------------------------------------------
904 As specified in the section about ``gnatfind``, the pattern can be a
905 regular expression. Two kinds of regular expressions
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.
912 Here is a more formal grammar:
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
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``.
928 The following is the form of a regular expression, expressed in same BNF
929 style as is found in the Ada Reference Manual:
933 regexp ::= term {| term} -- alternation (term or term ...)
935 term ::= item {item} -- concatenation (item then item)
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
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
950 char ::= any character, including special characters
951 nschar ::= any character except ()[].*+?^
953 Here are a few examples:
956 will match any of the two strings ``abcde`` and ``fghi``,
959 will match any string like ``abd``, ``abcd``, ``abccd``,
960 ``abcccd``, and so on,
963 will match any string which has only lowercase characters in it (and at
967 .. _Examples_of_gnatxref_Usage:
969 Examples of ``gnatxref`` Usage
970 ------------------------------
975 For the following examples, we will consider the following units:
982 3: procedure Foo (B : in Integer);
989 1: package body Main is
990 2: procedure Foo (B : in Integer) is
1001 2: procedure Print (B : Integer);
1004 The first thing to do is to recompile your application (for instance, in
1005 that case just by doing a ``gnatmake main``, so that GNAT generates
1006 the cross-referencing information.
1007 You can then issue any of the following commands:
1009 * ``gnatxref main.adb``
1010 ``gnatxref`` generates cross-reference information for main.adb
1011 and every unit 'with'ed by main.adb.
1013 The output would be:
1022 Ref: main.adb 4:13 5:13 6:19
1025 Ref: main.adb 6:8 7:8
1042 Ref: main.adb 6:12 7:12
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.
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.
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
1058 Using ``gnatxref`` with ``vi``
1059 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1061 ``gnatxref`` can generate a tags file output, which can be used
1062 directly from ``vi``. Note that the standard version of ``vi``
1063 will not work properly with overloaded symbols. Consider using another
1064 free implementation of ``vi``, such as ``vim``.
1068 $ gnatxref -v gnatfind.adb > tags
1071 The following command will generate the tags file for ``gnatfind`` itself
1072 (if the sources are in the search path!):
1076 $ gnatxref -v gnatfind.adb > tags
1078 From ``vi``, you can then use the command :samp:`:tag {entity}`
1079 (replacing ``entity`` by whatever you are looking for), and vi will
1080 display a new file with the corresponding declaration of entity.
1083 .. _Examples_of_gnatfind_Usage:
1085 Examples of ``gnatfind`` Usage
1086 ------------------------------
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
1093 The directories will be printed as well (as the ``-f``
1096 The output will look like:
1100 directory/main.ads:106:14: xyz <= declaration
1101 directory/main.adb:24:10: xyz <= body
1102 directory/foo.ads:45:23: xyz <= declaration
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
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.
1112 The output will look like:
1116 directory/main.ads:106:14: xyz <= declaration
1118 directory/main.adb:24:10: xyz <= body
1120 directory/foo.ads:45:23: xyz <= declaration
1123 This can make it easier to find exactly the location your are looking
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.
1133 * ``gnatfind main.ads:123``
1134 Find declarations and bodies for all entities that are referenced on
1135 line 123 of main.ads.
1137 This is the same as ``gnatfind "*":main.adb:123```
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.
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.
1149 .. _The_Ada_to_HTML_Converter_gnathtml:
1151 The Ada to HTML Converter ``gnathtml``
1152 ======================================
1154 .. index:: ! gnathtml
1156 ``gnathtml`` is a Perl script that allows Ada source files to be browsed using
1157 standard Web browsers. For installation information, see :ref:`Installing_gnathtml`.
1159 Ada reserved keywords are highlighted in a bold font and Ada comments in
1160 a blue font. Unless your program was compiled with the gcc :switch:`-gnatx`
1161 switch to suppress the generation of cross-referencing information, user
1162 defined variables and types will appear in a different color; you will
1163 be able to click on any identifier and go to its declaration.
1165 .. _Invoking_gnathtml:
1167 Invoking ``gnathtml``
1168 ---------------------
1170 The command line is as follows:
1174 $ perl gnathtml.pl [ switches ] ada-files
1176 You can specify as many Ada files as you want. ``gnathtml`` will generate
1177 an html file for every ada file, and a global file called :file:`index.htm`.
1178 This file is an index of every identifier defined in the files.
1180 The following switches are available:
1182 .. index:: -83 (gnathtml)
1185 Only the Ada 83 subset of keywords will be highlighted.
1187 .. index:: -cc (gnathtml)
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.
1193 .. index:: -d (gnathtml)
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.
1201 .. index:: -D (gnathtml)
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.
1207 .. index:: -ext (gnathtml)
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`.
1213 .. index:: -f (gnathtml)
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
1221 .. index:: -l (gnathtml)
1224 If this switch is provided and ``number`` is not 0, then
1225 ``gnathtml`` will number the html files every ``number`` line.
1227 .. index:: -I (gnathtml)
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.
1234 .. index:: -o (gnathtml)
1237 Specify the output directory for html files. By default, gnathtml will
1238 saved the generated html files in a subdirectory named :file:`html/`.
1240 .. index:: -p (gnathtml)
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.
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.
1252 .. index:: -sc (gnathtml)
1255 This switch allows you to change the color used for symbol
1257 The default value is red. The color argument can be any name accepted by html.
1259 .. index:: -t (gnathtml)
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
1268 .. _Installing_gnathtml:
1270 Installing ``gnathtml``
1271 -----------------------
1273 ``Perl`` needs to be installed on your machine to run this script.
1274 ``Perl`` is freely available for almost every architecture and
1275 operating system via the Internet.
1277 On Unix systems, you may want to modify the first line of the script
1278 ``gnathtml``, to explicitly specify where Perl
1279 is located. The syntax of this line is:
1283 #!full_path_name_to_perl
1285 Alternatively, you may run the script using the following command line:
1289 $ perl gnathtml.pl [ switches ] files
1294 .. -- +---------------------------------------------------------------------+
1295 .. -- | The following sections are present only in the PRO and GPL editions |
1296 .. -- +---------------------------------------------------------------------+
1298 .. only:: PRO or GPL
1300 .. _The_Ada-to-XML_converter_gnat2xml:
1302 The Ada-to-XML converter ``gnat2xml``
1303 =====================================
1305 .. index:: ! gnat2xml
1306 .. index:: XML generation
1308 The ``gnat2xml`` tool is an ASIS-based utility that converts
1309 Ada source code into XML.
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``.
1316 .. _Switches_for_``gnat2xml``:
1318 Switches for ``gnat2xml``
1319 -------------------------
1321 ``gnat2xml`` takes Ada source code as input, and produces XML
1322 that conforms to the schema.
1328 $ gnat2xml [options] filenames [-files filename] [-cargs gcc_switches]
1333 Generate usage information and quit, ignoring all other options
1339 Print version and quit, ignoring all other options
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.
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.
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.
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.
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`).
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.
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.
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
1385 :switch:`-I{include-dir}`
1386 Directories to search for dependencies.
1387 You can also set the ADA_INCLUDE_PATH environment variable for this.
1390 Debugging version, with interspersed source, and a more
1391 compact representation of "sloc". This version does not conform
1394 :switch:`--rep-clauses`
1395 generate representation clauses (see :ref:`Generating_Representation_Clauses`).
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.
1403 :switch:`--ignore={filename}`
1404 Do not process the sources listed in a specified file. This option cannot
1405 be used in incremental mode.
1413 :switch:`-cargs` ...
1414 Options to pass to gcc
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.
1424 $ gnat2xml -v -output-dir=xml-files *.ad[sb]
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.
1437 The distribution includes two other programs that are related to
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:
1448 $ gnat2xsd > ada-schema.xsd
1451 ``gnat2xml`` generates XML files that will validate against
1452 :file:`ada-schema.xsd`.
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.
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.
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.
1474 .. _Structure_of_the_XML:
1476 Structure of the XML
1477 --------------------
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.
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.
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
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:
1505 type T is range 1..10;
1506 X, Y : constant T := 1;
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.
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:
1521 ------------------------------------------------------------------------------
1522 -- 18.3 function Assignment_Expression
1523 ------------------------------------------------------------------------------
1525 function Assignment_Expression
1526 (Statement : Asis.Statement)
1527 return Asis.Expression;
1529 ------------------------------------------------------------------------------
1531 -- Returns the expression from the right hand side of the assignment.
1533 -- Returns Element_Kinds:
1537 The corresponding sub-element of type Assignment_Statement is:
1541 <xsd:element name="assignment_expression_q" type="Expression_Class"/>
1543 where Expression_Class is defined by an xsd:choice of all the
1544 various kinds of expression.
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.
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").
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
1561 The root of the tree is a Compilation_Unit, with attributes:
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
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 ...``.
1571 * def_name is the same as unit_full_name for library units; for subunits,
1572 it is just the simple name.
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.
1580 Defining occurrences have these attributes:
1582 * def_name is the simple name of the declared entity, as written in the Ada
1585 * def is a unique URI of the form:
1589 ada://kind/fully/qualified/name
1593 * kind indicates the kind of Ada entity being declared (see below), and
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.
1601 * type is the type of the declared object, or ``null`` for
1602 declarations of things other than objects.
1604 Usage occurrences have these attributes:
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.
1610 * ref is the same as the def of the corresponding defining
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.
1617 Literal elements have this attribute:
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.
1627 Elements that can syntactically represent names and expressions (which
1628 includes usage occurrences, plus function calls and so forth) have this
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"
1637 Pragma elements have this attribute:
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").
1647 Defining occurrences of formal parameters and generic formal objects have this
1650 * mode indicates that the parameter is of mode 'in', 'in out', or 'out'.
1652 All elements other than Not_An_Element have this attribute:
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.
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:
1671 tagged_incomplete_type
1686 generalized_iterator
1704 generic_package_renaming
1705 generic_procedure_renaming
1706 generic_function_renaming
1722 package_instantiation
1723 procedure_instantiation
1724 function_instantiation
1727 formal_incomplete_type
1731 formal_package_declaration_with_box
1733 .. _Generating_Representation_Clauses:
1735 Generating Representation Clauses
1736 ---------------------------------
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.
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``.
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.
1755 The representation clauses are surrounded by comment elements to
1756 indicate that they are automatically generated, something like this:
1760 <comment text="--gen+">
1762 <attribute_definition_clause>
1764 <comment text="--gen-">
1768 .. only:: PRO or GPL
1770 .. _The_Coding_Standard_Verifier_gnatcheck:
1772 The Coding Standard Verifier ``gnatcheck``
1773 ==========================================
1775 .. index:: ! gnatcheck
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.
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``.
1786 For full details, plese refer to :title:`GNATcheck Reference Manual`.
1790 .. only:: PRO or GPL
1792 .. _The_GNAT_Metrics_Tool_gnatmetric:
1794 The GNAT Metrics Tool ``gnatmetric``
1795 ====================================
1797 .. index:: ! gnatmetric
1798 .. index:: Metric tool
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.
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``.
1811 The ``gnatmetric`` command has the form
1815 $ gnatmetric [ switches ] { filename }
1819 * ``switches`` specify the metrics to compute and define the destination for
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.
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.
1833 The following subsections describe the various switches accepted by
1834 ``gnatmetric``, organized by category.
1836 .. _Output_File_Control-gnatmetric:
1841 .. index:: Output file control in gnatmetric
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.
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.
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
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.
1874 The following switches control the ``gnatmetric`` output:
1876 .. index:: --generate-xml-output (gnatmetric)
1878 :switch:`--generate-xml-output`
1879 Generate XML output.
1881 .. index:: --generate-xml-schema (gnatmetric)
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
1889 .. index:: --no-text-output (gnatmetric)
1892 :switch:`--no-text-output`
1893 Do not generate the output in text form (implies :switch:`-x`).
1895 .. index:: --output-dir (gnatmetric)
1898 :switch:`--output-dir={output_dir}`
1899 Put text files with detailed metrics into ``output_dir``.
1901 .. index:: --output-suffix (gnatmetric)
1904 :switch:`--output-suffix={file_suffix}`
1905 Use ``file_suffix``, instead of :file:`.metrix`
1906 in the name of the output file.
1908 .. index:: --global-file-name (gnatmetric)
1910 :switch:`--global-file-name={file_name}`
1911 Put global metrics into ``file_name``.
1913 .. index:: --xml-file-name (gnatmetric)
1916 :switch:`--xml-file-name={file_name}`
1917 Put the XML output into ``file_name``
1918 (also implies :switch:`--generate-xml-output`).
1920 .. index:: --short-file-names (gnatmetric)
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
1930 .. index:: --wide-character-encoding (gnatmetric)
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:
1936 * *8* - UTF-8 encoding
1938 * *b* - Brackets encoding (default value)
1941 .. index:: Disable Metrics For Local Units in gnatmetric
1943 .. _Disable_Metrics_For_Local_Units:
1945 Disable Metrics For Local Units
1946 -------------------------------
1948 ``gnatmetric`` relies on the GNAT compilation model --
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.
1954 By default, ``gnatmetric`` will also compute all metrics for certain
1955 kinds of locally declared program units:
1957 * subprogram (and generic subprogram) bodies;
1959 * package (and generic package) specs and bodies;
1961 * task object and type specifications and bodies;
1963 * protected object and type specifications and bodies.
1965 .. index:: Eligible local unit (for gnatmetric)
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.
1971 Note that a subprogram declaration, generic instantiation,
1972 or renaming declaration only receives metrics
1973 computation when it appear as the outermost entity
1976 Suppression of metrics computation for eligible local units can be
1977 obtained via the following switch:
1980 .. index:: --no-local-metrics (gnatmetric)
1983 :switch:`--no-local-metrics`
1984 Do not compute detailed metrics for eligible local program units.
1987 .. _Specifying_a_set_of_metrics_to_compute:
1989 Specifying a set of metrics to compute
1990 --------------------------------------
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.
1998 .. _Line_Metrics_Control:
2000 Line Metrics Control
2001 ^^^^^^^^^^^^^^^^^^^^
2003 .. index:: Line metrics control in gnatmetric
2005 For each source file, and for each of its eligible local program
2006 units, ``gnatmetric`` computes the following metrics:
2008 * the total number of lines;
2010 * the total number of code lines (i.e., non-blank lines that are not
2013 * the number of comment lines
2015 * the number of code lines containing end-of-line comments;
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
2021 * the number of empty lines and lines containing only space characters
2022 and/or format effectors (blank lines)
2024 * the average number of code lines in subprogram bodies, task bodies,
2025 entry bodies and statement sequences in package bodies
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.
2032 You can use the following switches to select the specific line metrics
2036 .. index:: --lines (gnatmetric)
2037 .. index:: --no-lines (gnatmetric)
2040 :switch:`--lines-all`
2041 Report all the line metrics
2044 :switch:`--no-lines-all`
2045 Do not report any of line metrics
2049 Report the number of all lines
2052 :switch:`--no-lines`
2053 Do not report the number of all lines
2056 :switch:`--lines-code`
2057 Report the number of code lines
2060 :switch:`--no-lines-code`
2061 Do not report the number of code lines
2064 :switch:`--lines-comment`
2065 Report the number of comment lines
2068 :switch:`--no-lines-comment`
2069 Do not report the number of comment lines
2072 :switch:`--lines-eol-comment`
2073 Report the number of code lines containing
2074 end-of-line comments
2077 :switch:`--no-lines-eol-comment`
2078 Do not report the number of code lines containing
2079 end-of-line comments
2082 :switch:`--lines-ratio`
2083 Report the comment percentage in the program text
2086 :switch:`--no-lines-ratio`
2087 Do not report the comment percentage in the program text
2090 :switch:`--lines-blank`
2091 Report the number of blank lines
2094 :switch:`--no-lines-blank`
2095 Do not report the number of blank lines
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.
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.
2108 :switch:`--lines-spark`
2109 Report the number of lines written in SPARK.
2112 :switch:`--no-lines-spark`
2113 Do not report the number of lines written in SPARK.
2116 .. _Syntax_Metrics_Control:
2118 Syntax Metrics Control
2119 ^^^^^^^^^^^^^^^^^^^^^^
2121 .. index:: Syntax metrics control in gnatmetric
2123 ``gnatmetric`` computes various syntactic metrics for the
2124 outermost unit and for each eligible local unit:
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:
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."
2139 This means for example that each enumeration literal adds one to
2140 the count, as well as each subprogram parameter.
2142 * *Maximal static nesting level of inner program units*
2143 According to :title:`Ada Reference Manual`, 10.1(1):
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."
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`).
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.
2163 For the outermost unit in the file, ``gnatmetric`` additionally
2164 computes the following metrics:
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).
2174 This metric is computed for bodies and subunits. The metric is
2175 equal to a total number of subprogram bodies in the compilation
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.
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.
2192 Along with the total number of public types, the following
2193 types are counted and reported separately:
2197 * *Root tagged types^ (abstract, non-abstract, private,
2198 non-private). Type extensions are *not* counted
2200 * *Private types* (including private extensions)
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.
2215 By default, all the syntax metrics are reported. You can use the following
2216 switches to select specific syntax metrics.
2219 .. index:: --syntax (gnatmetric)
2220 .. index:: --no-syntax (gnatmetric)
2223 :switch:`--syntax-all`
2224 Report all the syntax metrics
2227 :switch:`--no-syntax-all`
2228 Do not report any of syntax metrics
2231 :switch:`--declarations`
2232 Report the total number of declarations
2235 :switch:`--no-declarations`
2236 Do not report the total number of declarations
2239 :switch:`--statements`
2240 Report the total number of statements
2243 :switch:`--no-statements`
2244 Do not report the total number of statements
2247 :switch:`--public-subprograms`
2248 Report the number of public subprograms in a compilation unit
2251 :switch:`--no-public-subprograms`
2252 Do not report the number of public subprograms in a compilation unit
2255 :switch:`--all-subprograms`
2256 Report the number of all the subprograms in a compilation unit
2259 :switch:`--no-all-subprograms`
2260 Do not report the number of all the subprograms in a compilation unit
2263 :switch:`--public-types`
2264 Report the number of public types in a compilation unit
2267 :switch:`--no-public-types`
2268 Do not report the number of public types in a compilation unit
2271 :switch:`--all-types`
2272 Report the number of all the types in a compilation unit
2275 :switch:`--no-all-types`
2276 Do not report the number of all the types in a compilation unit
2279 :switch:`--unit-nesting`
2280 Report the maximal program unit nesting level
2283 :switch:`--no-unit-nesting`
2284 Do not report the maximal program unit nesting level
2287 :switch:`--construct-nesting`
2288 Report the maximal construct nesting level
2291 :switch:`--no-construct-nesting`
2292 Do not report the maximal construct nesting level
2294 :switch:`--param-number`
2295 Report the number of subprogram parameters
2298 :switch:`--no-param-number`
2299 Do not report the number of subprogram parameters
2302 .. _Contract_Metrics_Control:
2304 Contract Metrics Control
2305 ^^^^^^^^^^^^^^^^^^^^^^^^
2307 .. index:: Contract metrics control in gnatmetric
2309 :switch:`--contract-all`
2310 Report all the contract metrics
2313 :switch:`--no-contract-all`
2314 Do not report any of the contract metrics
2317 :switch:`--contract`
2318 Report the number of public subprograms with contracts
2321 :switch:`--no-contract`
2322 Do not report the number of public subprograms with contracts
2326 Report the number of public subprograms with postconditions
2330 Do not report the number of public subprograms with postconditions
2333 :switch:`--contract-complete`
2334 Report the number of public subprograms with complete contracts
2337 :switch:`--no-contract-complete`
2338 Do not report the number of public subprograms with complete contracts
2341 :switch:`--contract-all`
2342 Report the McCabe complexity of public subprograms
2345 :switch:`--no-contract-all`
2346 Do not report the McCabe complexity of public subprograms
2349 .. _Complexity_Metrics_Control:
2351 Complexity Metrics Control
2352 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2354 .. index:: Complexity metrics control in gnatmetric
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:
2361 * McCabe cyclomatic complexity;
2363 * McCabe essential complexity;
2365 * maximal loop nesting level;
2367 * extra exit points (for subprograms);
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>`_
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:
2378 * the complexity introduced by control
2379 statements only, without taking into account short-circuit forms
2380 (referred as ``statement complexity`` in ``gnatmetric`` output),
2382 * the complexity introduced by short-circuit control forms only
2383 (referred as ``expression complexity`` in ``gnatmetric`` output),
2387 cyclomatic complexity, which is the sum of these two values
2388 (referred as ``cyclomatic complexity`` in ``gnatmetric`` output).
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.
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
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.
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.
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.
2427 By default, all the complexity metrics are reported. For more fine-grained
2428 control you can use the following switches:
2431 .. index:: --complexity (gnatmetric)
2432 .. index:: --no-complexity (gnatmetric)
2435 :switch:`--complexity-all`
2436 Report all the complexity metrics
2439 :switch:`--no-complexity-all`
2440 Do not report any of the complexity metrics
2443 :switch:`--complexity-cyclomatic`
2444 Report the McCabe Cyclomatic Complexity
2447 :switch:`--no-complexity-cyclomatic`
2448 Do not report the McCabe Cyclomatic Complexity
2451 :switch:`--complexity-essential`
2452 Report the Essential Complexity
2455 :switch:`--no-complexity-essential`
2456 Do not report the Essential Complexity
2459 :switch:`--loop-nesting`
2460 Report maximal loop nesting level
2463 :switch:`-no-loop-nesting`
2464 Do not report maximal loop nesting level
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.
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
2477 .. index:: --no-treat-exit-as-goto (gnatmetric)
2480 :switch:`--no-treat-exit-as-goto`
2481 Do not consider ``exit`` statements as ``goto``\ s when
2482 computing Essential Complexity
2484 .. index:: --no-static-loop (gnatmetric)
2487 :switch:`--no-static-loop`
2488 Do not consider static loops when computing cyclomatic complexity
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.
2499 :switch:`--no-extra-exit-points`
2500 Do not report the extra exit points for subprogram bodies
2503 .. _Coupling_Metrics_Control:
2505 Coupling Metrics Control
2506 ^^^^^^^^^^^^^^^^^^^^^^^^
2508 .. index:: Coupling metrics control in gnatmetric
2510 .. index:: Coupling metrics (in gnatmetric)
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.
2516 ``gnatmetric`` computes the following coupling metrics:
2519 * *object-oriented coupling*, for classes in traditional object-oriented
2522 * *unit coupling*, for all the program units making up a program;
2524 * *control coupling*, reflecting dependencies between a unit and
2525 other units that contain subprograms.
2527 .. index:: fan-out coupling
2528 .. index:: efferent coupling
2530 Two kinds of coupling metrics are computed:
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
2537 .. index:: fan-in coupling
2538 .. index:: afferent coupling
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
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.
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.
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.
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.
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'.
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
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).
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.
2600 The following simple example illustrates the difference between unit coupling
2601 and control coupling metrics:
2606 function F_1 (I : Integer) return Integer;
2610 type T_2 is new Integer;
2613 package body Lib_1 is
2614 function F_1 (I : Integer) return Integer is
2620 with Lib_2; use Lib_2;
2623 function Fun (I : Integer) return Integer;
2626 with Lib_1; use Lib_1;
2627 package body Pack is
2628 function Fun (I : Integer) return Integer is
2634 If we apply ``gnatmetric`` with the :switch:`--coupling-all` option to
2635 these units, the result will be:
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
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
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
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.
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.
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.
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
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.
2684 By default, all the coupling metrics are reported. You can use the following
2685 switches to select specific syntax metrics.
2687 .. index:: --tagged-coupling (gnatmetric)
2688 .. index:: --hierarchy-coupling (gnatmetric)
2689 .. index:: --unit-coupling (gnatmetric)
2690 .. index:: --control-coupling (gnatmetric)
2692 :switch:`--coupling-all`
2693 Report all the coupling metrics
2696 :switch:`--tagged-coupling-out`
2697 Report tagged (class) fan-out coupling
2700 :switch:`--tagged-coupling-in`
2701 Report tagged (class) fan-in coupling
2704 :switch:`--hierarchy-coupling-out`
2705 Report hierarchy (category) fan-out coupling
2708 :switch:`--hierarchy-coupling-in`
2709 Report hierarchy (category) fan-in coupling
2712 :switch:`--unit-coupling-out`
2713 Report unit fan-out coupling
2716 :switch:`--unit-coupling-in`
2717 Report unit fan-in coupling
2720 :switch:`--control-coupling-out`
2721 Report control fan-out coupling
2724 :switch:`--control-coupling-in`
2725 Report control fan-in coupling
2728 .. _Other_gnatmetric_Switches:
2730 Other ``gnatmetric`` Switches
2731 -----------------------------
2733 Additional ``gnatmetric`` switches are as follows:
2736 .. index:: --version (gnatmetric)
2739 Display copyright and version, then exit disregarding all other options.
2742 .. index:: --help (gnatmetric)
2745 Display usage, then exit disregarding all other options.
2748 .. index:: -P (gnatmetric)
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.
2757 .. index:: -U (gnatmetric)
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
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
2773 .. index:: -X (gnatmetric)
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.
2780 .. index:: --RTS (gnatmetric)
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`).
2787 .. index:: --subdirs=dir (gnatmetric)
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.
2796 .. index:: --files (gnatmetric)
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.
2805 .. index:: --ignore (gnatmetric)
2807 :switch:`--ignore={filename}`
2808 Do not process the sources listed in a specified file.
2811 .. index:: --verbose (gnatmetric)
2815 ``gnatmetric`` generates version information and then
2816 a trace of sources being processed.
2819 .. index:: --quiet (gnatmetric)
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.
2833 Some switches have a short form, mostly for legacy reasons,
2836 .. index:: -x (gnatmetric)
2839 :switch:`--generate-xml-output`
2841 .. index:: -xs (gnatmetric)
2844 :switch:`--generate-xml-schema`
2846 .. index:: -nt (gnatmetric)
2849 :switch:`--no-text-output`
2851 .. index:: -d (gnatmetric)
2853 :switch:`-d {output-dir}`
2854 :switch:`--output-dir`
2856 .. index:: -o (gnatmetric)
2858 :switch:`-o {file-suffix}`
2859 :switch:`--output-suffix`
2861 .. index:: -og (gnatmetric)
2863 :switch:`-og {file-name}`
2864 :switch:`--global-file-name`
2866 .. index:: -ox (gnatmetric)
2868 :switch:`-ox {file-name}`
2869 :switch:`--xml-file-name`
2871 .. index:: -sfn (gnatmetric)
2874 :switch:`--short-file-names`
2876 .. index:: -W (gnatsmetric)
2879 :switch:`--wide-character-encoding={e}`
2881 .. index:: -nolocal (gnatmetric)
2884 :switch:`--no-local-metrics`
2886 .. index:: -ne (gnatmetric)
2889 :switch:`--no-treat-exit-as-goto`
2891 .. index:: -files (gnatmetric)
2893 :switch:`-files {filename}`
2896 .. index:: -v (gnatmetric)
2901 .. index:: -q (gnatmetric)
2906 .. only:: PRO or GPL
2908 .. _The_GNAT_Pretty_Printer_gnatpp:
2910 The GNAT Pretty Printer ``gnatpp``
2911 ==================================
2914 .. index:: pretty printer
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.
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``.
2927 ``gnatpp`` cannot process sources that contain preprocessing
2930 The ``gnatpp`` command has the form
2934 $ gnatpp [ switches ] filename
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
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
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.
2952 .. _Switches_for_gnatpp:
2954 Switches for ``gnatpp``
2955 -----------------------
2957 The following subsections describe the various switches accepted by
2958 ``gnatpp``, organized by category.
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
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
2974 .. _Alignment_Control:
2979 .. index:: Alignment control in gnatpp
2981 Programs can be easier to read if certain constructs are vertically aligned.
2982 By default, alignment of the following constructs is set ON:
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.
2990 In addition, ``in`` and ``out`` in parameter specifications are lined up.
2992 .. index:: --no-alignment (gnatpp)
2993 .. index:: --alignment (gnatpp)
2994 .. index:: --no-align-modes (gnatpp)
2997 :switch:`--no-alignment`
2998 Set alignment to OFF
3001 :switch:`--alignment`
3005 :switch:`--no-align-modes`
3006 Do not line up ``in`` and ``out`` in parameter specifications.
3014 .. index:: Casing control in gnatpp
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.
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.
3027 (Note: the casing switches are not yet fully supported in the
3028 libadalang-based version of gnatpp.)
3030 .. index:: --name-case-as-declared (gnatpp)
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)
3036 .. index:: --name-upper-case (gnatpp)
3038 :switch:`--name-upper-case`
3039 Names are in upper case
3041 .. index:: --name-lower-case (gnatpp)
3043 :switch:`--name-lower-case`
3044 Names are in lower case
3046 .. index:: --name-mixed-case (gnatpp)
3048 :switch:`--name-mixed-case`
3049 Names are in mixed case
3051 .. index:: --attribute-lower-case (gnatpp)
3053 :switch:`--attribute-lower-case`
3054 Attribute designators are lower case
3056 .. index:: --attribute-upper-case (gnatpp)
3058 :switch:`--attribute-upper-case`
3059 Attribute designators are upper case
3061 .. index:: --attribute-mixed-case (gnatpp)
3063 :switch:`--attribute-mixed-case`
3064 Attribute designators are mixed case (this is the default)
3066 .. index:: --keyword-lower-case (gnatpp)
3068 :switch:`--keyword-lower-case`
3069 Keywords (technically, these are known in Ada as *reserved words*) are
3070 lower case (this is the default)
3072 .. index:: --keyword-upper-case (gnatpp)
3074 :switch:`--keyword-upper-case`
3075 Keywords are upper case
3077 .. index:: --enum-case-as-declared (gnatpp)
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.
3083 .. index:: --enum-upper-case (gnatpp)
3085 :switch:`--enum-upper-case`
3086 Enumeration literals are in upper case. Overrides -n casing
3089 .. index:: --enum-lower-case (gnatpp)
3091 :switch:`--enum-lower-case`
3092 Enumeration literals are in lower case. Overrides -n casing
3095 .. index:: --enum-mixed-case (gnatpp)
3097 :switch:`--enum-mixed-case`
3098 Enumeration literals are in mixed case. Overrides -n casing
3101 .. index:: --type-case-as-declared (gnatpp)
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.
3108 .. index:: --type-upper-case (gnatpp)
3110 :switch:`--type-upper-case`
3111 Names introduced by type and subtype declarations are always in
3112 upper case. Overrides -n casing setting.
3114 .. index:: --type-lower-case (gnatpp)
3116 :switch:`--type-lower-case`
3117 Names introduced by type and subtype declarations are always in
3118 lower case. Overrides -n casing setting.
3120 .. index:: --type-mixed-case (gnatpp)
3122 :switch:`--type-mixed-case`
3123 Names introduced by type and subtype declarations are always in
3124 mixed case. Overrides -n casing setting.
3126 .. index:: --number-upper-case (gnatpp)
3128 :switch:`--number-upper-case`
3129 Names introduced by number declarations are always in
3130 upper case. Overrides -n casing setting.
3132 .. index:: --number-lower-case (gnatpp)
3134 :switch:`--number-lower-case`
3135 Names introduced by number declarations are always in
3136 lower case. Overrides -n casing setting.
3138 .. index:: --number-mixed-case (gnatpp)
3140 :switch:`--number-mixed-case`
3141 Names introduced by number declarations are always in
3142 mixed case. Overrides -n casing setting.
3144 .. index:: --pragma-lower-case (gnatpp)
3146 :switch:`--pragma-lower-case`
3147 Pragma names are lower case
3149 .. index:: --pragma-upper-case (gnatpp)
3151 :switch:`--pragma-upper-case`
3152 Pragma names are upper case
3154 .. index:: --pragma-mixed-case (gnatpp)
3156 :switch:`--pragma-mixed-case`
3157 Pragma names are mixed case (this is the default)
3160 .. index:: --syntax-only (gnatpp)
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.
3168 .. index:: --dictionary (gnatpp)
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
3176 To supply more than one dictionary file,
3177 use several ``--dictionary`` switches.
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.
3184 .. index:: --dictionary=- (gnatpp)
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
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`.
3195 The :switch:`--dictionary=-` and
3196 :switch:`--dictionary={file}` switches are mutually
3199 This group of ``gnatpp`` switches controls the layout of comments and
3200 complex syntactic constructs. See :ref:`Formatting_Comments` for details
3204 .. index:: -c (gnatpp)
3207 :switch:`--comments-unchanged`
3208 All comments remain unchanged.
3211 :switch:`--comments-gnat-indentation`
3212 GNAT-style comment line indentation.
3213 This is the default.
3216 :switch:`--comments-gnat-beginning`
3217 GNAT-style comment beginning.
3220 :switch:`--comments-fill`
3221 Fill comment blocks.
3224 :switch:`--comments-special`
3225 Keep unchanged special form comments.
3226 This is the default.
3229 .. index:: --comments-only (gnatpp)
3231 :switch:`--comments-only`
3232 Format just the comments.
3234 .. index:: --no-end-id (gnatpp)
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.
3241 .. index:: --no-separate-is (gnatpp)
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.
3248 .. index:: --separate-loop (gnatpp)
3251 :switch:`--separate-loop`
3252 Place the keyword ``loop`` in FOR and WHILE loop statements
3255 .. index:: --no-separate-then (gnatpp)
3258 :switch:`--separate-then`
3259 Place the keyword ``then`` in IF statements
3262 .. index:: --no-separate-loop (gnatpp)
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.
3270 .. index:: --no-separate-then (gnatpp)
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.
3278 .. index:: --separate-loop-then (gnatpp)
3281 :switch:`--separate-loop-then`
3282 Equivalent to :switch:`--separate-loop` :switch:`--separate-then`.
3284 .. index:: --no-separate-loop-then (gnatpp)
3287 :switch:`--no-separate-loop-then`
3288 Equivalent to :switch:`--no-separate-loop` :switch:`--no-separate-then`.
3290 .. index:: --use-on-new-line (gnatpp)
3293 :switch:`--use-on-new-line`
3294 Start each USE clause in a context clause from a separate line.
3297 .. index:: --insert-blank-lines (gnatpp)
3300 :switch:`--insert-blank-lines`
3301 Insert blank lines where appropriate (between bodies and other large
3304 .. index:: --preserve-blank-lines (gnatpp)
3307 :switch:`--preserve-blank-lines`
3308 Preserve blank lines in the input. By default, gnatpp will squeeze
3309 multiple blank lines down to one.
3311 .. index:: --preserve-line-breaks (gnatpp)
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
3318 .. index:: --source-line-breaks (gnatpp)
3320 :switch:`--source-line-breaks`
3321 Keep the line breaks from the source; do not insert or delete any
3324 .. index:: --spaces-only (gnatpp)
3326 :switch:`--spaces-only`
3327 Disable all formatting except for inserting and removing spaces.
3328 This implies --source-line-breaks.
3330 The ``--comments`` switches are compatible with one another, except
3331 that the ``--comments-unchanged`` switch disables all other comment
3332 formatting switches.
3335 .. _General_Text_Layout_Control:
3337 General Text Layout Control
3338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
3340 These switches allow control over line length and indentation.
3342 .. index:: --max-line-length (gnatpp)
3344 :switch:`--max-line-length={nnn}`
3345 Maximum line length, ``nnn`` from 32...256, the default value is 79
3348 .. index:: --indentation (gnatpp)
3350 :switch:`--indentation={nnn}`
3351 Indentation level, ``nnn`` from 1...9, the default value is 3
3354 .. index:: --indent-continuation (gnatpp)
3356 :switch:`--indent-continuation={nnn}`
3357 Indentation level for continuation lines (relative to the line being
3358 continued), ``nnn`` from 1...9.
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)
3365 .. _Other_Formatting_Options:
3367 Other Formatting Options
3368 ^^^^^^^^^^^^^^^^^^^^^^^^
3370 These switches control other formatting not listed above.
3372 .. index:: --decimal-grouping (gnatpp)
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
3382 .. index:: --based-grouping (gnatpp)
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#``.
3390 .. index:: --split-line-before-record (gnatpp)
3392 :switch:`--split-line-before-record`
3393 Split the line just before ``record`` in a record type declaration.
3396 .. index:: --indent-named-statements (gnatpp)
3398 :switch:`--indent-named-statements`
3399 Named block and loop statements are indented with respect to
3403 .. index:: --split-line-before-op (gnatpp)
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.
3411 .. index:: --RM-style-spacing (gnatpp)
3413 :switch:`--RM-style-spacing`
3414 Do not insert an extra blank before various occurrences of
3415 '(' and ':'. Alignment is off by default in this mode;
3416 use :switch:`--alignment` to turn it on.
3419 .. index:: --compact (gnatpp)
3420 .. index:: --no-compact (gnatpp)
3423 This is the default. In calls and similar, this packs as many
3424 subexpressions on the same line as possible. Example:
3429 (Short_One, Another_Short_One,
3430 A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
3432 :switch:`--no-compact`
3433 Turns off --compact mode. In calls and similar, if it is necessary
3434 to split a line between two subexpressions (because otherwise the
3435 construct would exceed --max-line-length), then all such subexpressions
3436 are placed on separate lines. Example:
3443 A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
3446 .. index:: --call_threshold (gnatpp)
3448 :switch:`--call_threshold={nnn}`
3449 If the number of parameter associations is greater than ``nnn`` and if at
3450 least one association uses named notation, start each association from
3451 a new line. If ``nnn`` is 0, no check for the number of associations
3452 is made; this is the default.
3455 .. index:: --par_threshold (gnatpp)
3457 :switch:`--par_threshold={nnn}`
3458 If the number of parameter specifications is greater than ``nnn``
3459 (or equal to ``nnn`` in case of a function), start each specification from
3460 a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then
3461 the ``is`` is placed on a separate line. This feature is disabled by default.
3463 .. index:: --vertical-enum-types (gnatpp)
3465 :switch:`--vertical-enum-types`
3466 Format enumeration type declarations "vertically", e.g. each
3467 enumeration literal goes on a separate line.
3469 .. index:: --vertical-array-types (gnatpp)
3471 :switch:`--vertical-array-types`
3472 Format array type declarations "vertically", e.g. for
3473 multidimensional arrays, each index_subtype_definition or
3474 discrete_subtype_definition goes on a separate line.
3476 .. index:: --vertical-named-aggregates (gnatpp)
3478 :switch:`--vertical-named-aggregates`
3479 Format aggregates "vertically" if named notation is used for all
3480 component_associations, e.g. each component_association
3481 goes on a separate line.
3483 .. index:: --vertical-case-alternatives (gnatpp)
3485 :switch:`--vertical-case-alternatives`
3486 Format case statements, case expressions, and variant parts with
3487 additional line breaks.
3490 .. _Setting_the_Source_Search_Path:
3492 Setting the Source Search Path
3493 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3495 To define the search path for the input source file, ``gnatpp``
3496 uses the same switches as the GNAT compiler, with the same effects:
3498 .. index:: -I (gnatpp)
3503 .. index:: -I- (gnatpp)
3507 .. index:: -gnatec (gnatpp)
3509 :switch:`-gnatec={path}`
3512 .. _Output_File_Control-gnatpp:
3517 By default the output overwrites the input file.
3518 The output may be redirected by the following switches:
3521 .. index:: --replace (gnatpp)
3524 This is the default.
3525 Replace the input source file with the reformatted output without
3526 creating any backup copy of the input source.
3529 .. index:: --output-dir (gnatpp)
3531 :switch:`--output-dir={dir}`
3532 Generate output file in directory :file:`dir` with the same name as
3533 the input file. If :file:`dir` is the same as the directory
3534 containing the input file, the input file is not processed; use
3535 ``--replace`` if you want to update the input file in
3539 .. index:: --pipe (gnatpp)
3542 Send the output to ``Standard_Output``
3545 .. index:: --output (gnatpp)
3547 :switch:`--output={output_file}`
3548 Write the output into ``output_file``.
3549 If ``output_file`` already exists, ``gnatpp`` terminates without
3550 reading or processing the input file.
3553 .. index:: --output-force (gnatpp)
3555 :switch:`--output-force={output_file}`
3556 Write the output into ``output_file``, overwriting the existing file
3557 (if one is present).
3560 .. index:: --replace-backup (gnatpp)
3562 :switch:`--replace-backup`
3563 Replace the input source file with the reformatted output, and copy the
3564 original input source into the file whose name is obtained by appending the
3565 :file:`.npp` suffix to the name of the input file.
3566 If a file with this name already exists, ``gnatpp`` terminates without
3567 reading or processing the input file.
3570 .. index:: --replace-force-backup (gnatpp)
3572 :switch:`--replace-force-backup`
3573 Like ``--replace-backup`` except that if the file with the specified name
3574 already exists, it is overwritten.
3577 .. index:: --eol (gnatpp)
3579 :switch:`--eol={xxx}`
3580 Specifies the line-ending style of the reformatted output file. The
3581 ``xxx`` string specified with the switch may be:
3583 * *dos* - MS DOS style, lines end with CR LF characters*
3584 * *crlf* - the same as *dos*
3585 * *unix* - UNIX style, lines end with LF character*
3586 * *lf* - the same as *unix*
3588 The default is to use the same end-of-line convention as the input.
3590 .. index:: --wide-character-encoding (gnatpp)
3592 :switch:`--wide-character-encoding={e}`
3593 Specify the wide character encoding method for the input and output
3594 files. ``e`` is one of the following:
3596 * *8* - UTF-8 encoding
3598 * *b* - Brackets encoding (default value)
3600 Options ``--output-file`` and ``--output-force`` are allowed only if
3601 the call to gnatpp contains only one file to reformat.
3603 Option ``--eol`` and ``--wide-character-encoding`` cannot be used together
3604 with the ``--pipe`` option.
3607 .. _Other_gnatpp_Switches:
3609 Other ``gnatpp`` Switches
3610 ^^^^^^^^^^^^^^^^^^^^^^^^^
3612 The additional ``gnatpp`` switches are defined in this subsection.
3615 .. index:: --version (gnatpp)
3618 Display copyright and version, then exit disregarding all other options.
3621 .. index:: --help (gnatpp)
3624 Display usage, then exit disregarding all other options.
3627 .. index:: -P (gnatpp)
3630 Indicates the name of the project file that describes the set of sources
3631 to be processed. The exact set of argument sources depends on other options
3632 specified; see below.
3635 .. index:: -U (gnatpp)
3638 If a project file is specified and no argument source is explicitly
3639 specified (either directly or by means of ``--files`` option), process
3640 all the units of the closure of the argument project. Otherwise this option
3644 :switch:`-U {main_unit}`
3645 If a project file is specified and no argument source is explicitly
3646 specified (either directly or by means of ``--files`` option), process
3647 the closure of units rooted at ``main_unit``. Otherwise this option
3651 .. index:: -X (gnatpp)
3653 :switch:`-X{name}={value}`
3654 Indicates that external variable ``name`` in the argument project
3655 has the value ``value``. Has no effect if no project is specified.
3658 .. index:: --RTS (gnatpp)
3660 :switch:`--RTS={rts-path}`
3661 Specifies the default location of the runtime library. Same meaning as the
3662 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
3665 .. index:: --incremental (gnatpp)
3667 :switch:`--incremental`
3668 Incremental processing on a per-file basis. Source files are only
3669 processed if they have been modified, or if files they depend on have
3670 been modified. This is similar to the way gnatmake/gprbuild only
3671 compiles files that need to be recompiled. A project file is required
3672 in this mode, and the gnat driver (as in *gnat pretty*) is not
3674 (Note: this switch is not yet supported in the libadalang-based
3678 .. index:: --pp-off (gnatpp)
3680 :switch:`--pp-off={xxx}`
3681 Use :switch:`--xxx` as the command to turn off pretty printing, instead
3682 of the default ``--!pp off``.
3685 .. index:: --pp-on (gnatpp)
3687 :switch:`--pp-on={xxx}`
3688 Use :switch:`--xxx` as the command to turn pretty printing back on, instead
3689 of the default ``--!pp on``.
3692 .. index:: --files (gnatpp)
3694 :switch:`--files={filename}`
3695 Take as arguments the files listed in text file ``file``.
3696 Text file ``file`` may contain empty lines that are ignored.
3697 Each nonempty line should contain the name of an existing file.
3698 Several such switches may be specified simultaneously.
3701 .. index:: --ignore (gnatpp)
3703 :switch:`--ignore={filename}`
3704 Do not process the sources listed in a specified file. This option cannot
3705 be used in incremental mode.
3707 .. index:: --jobs (gnatpp)
3709 :switch:`--jobs={n}`
3710 With ``--incremental``, use *n* ``gnatpp`` processes to perform
3711 pretty printing in parallel. If *n* is 0, then the maximum number
3712 processes is the number of core processors on the platform.
3715 .. index:: --verbose (gnatpp)
3721 .. index:: --quiet (gnatpp)
3726 If a project file is specified and no argument source is explicitly
3727 specified (either directly or by means of ``--files`` option), and no
3728 ``-U`` is specified, then the set of processed sources is
3729 all the immediate units of the argument project.
3732 .. _Formatting_Rules:
3737 The following subsections show how ``gnatpp`` treats white space,
3738 comments, program layout, and name casing.
3739 They provide detailed descriptions of the switches shown above.
3742 .. _Disabling_Pretty_Printing:
3744 Disabling Pretty Printing
3745 ^^^^^^^^^^^^^^^^^^^^^^^^^
3747 Pretty printing is highly heuristic in nature, and sometimes doesn't
3748 do exactly what you want. If you wish to format a certain region of
3749 code by hand, you can turn off pretty printing in that region by
3750 surrounding it with special comments that start with ``--!pp off``
3751 and ``--!pp on``. The text in that region will then be reproduced
3752 verbatim in the output with no formatting.
3754 To disable pretty printing for the whole file, put ``--!pp off`` at
3755 the top, with no following ``--!pp on``.
3757 The comments must appear on a line by themselves, with nothing
3758 preceding except spaces. The initial text of the comment must be
3759 exactly ``--!pp off`` or ``--!pp on`` (case sensitive), but may
3760 be followed by arbitrary additional text. For example:
3764 package Interrupts is
3765 --!pp off -- turn off pretty printing so "Interrupt_Kind" lines up
3766 type Interrupt_Kind is
3767 (Asynchronous_Interrupt_Kind,
3768 Synchronous_Interrupt_Kind,
3769 Green_Interrupt_Kind);
3770 --!pp on -- reenable pretty printing
3773 You can specify different comment strings using the ``--pp-off``
3774 and ``--pp-on`` switches. For example, if you say:
3778 $ gnatpp --pp-off=' pp-' *.ad?
3780 then gnatpp will recognize comments of the form
3781 ``-- pp-`` instead of ``--!pp off`` for disabling pretty
3782 printing. Note that the leading ``--`` of the comment is not
3783 included in the argument to these switches.
3786 .. _White_Space_and_Empty_Lines:
3788 White Space and Empty Lines
3789 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
3791 ``gnatpp`` does not have an option to control space characters.
3792 It will add or remove spaces according to the style illustrated by the
3793 examples in the :title:`Ada Reference Manual`.
3794 The output file will contain no lines with trailing white space.
3796 By default, a sequence of one or more blank lines in the input is
3797 converted to a single blank line in the output; multiple blank lines
3798 are squeezed down to one.
3799 The ``--preserve-blank-lines`` option
3800 turns off the squeezing; each blank line in the input is copied
3802 The ``--insert-blank-lines`` option
3803 causes additional blank lines to be inserted if not already
3804 present in the input (e.g. between bodies).
3807 .. _Formatting_Comments:
3812 Comments in Ada code are of two kinds:
3814 * a *whole-line comment*, which appears by itself (possibly preceded by
3815 white space) on a line
3817 * an *end-of-line comment*, which follows some other Ada code on
3820 A whole-line comment is indented according to the surrounding code,
3821 with some exceptions. Comments that start in column 1 are kept
3822 there. If possible, comments are not moved so far to the right that
3823 the maximum line length is exceeded. The ``--comments-unchanged``
3824 option turns off comment formatting. Special-form comments such as
3825 SPARK-style ``--#...`` are left alone.
3827 For an end-of-line comment, ``gnatpp`` tries to leave the same
3828 number of spaces between the end of the preceding Ada code and the
3829 beginning of the comment as appear in the original source.
3831 The ``--comments-gnat-beginning`` switch (GNAT style comment
3832 beginning) has the following effect:
3834 * For each whole-line comment that does not end with two hyphens,
3835 ``gnatpp`` inserts spaces if necessary after the starting two
3836 hyphens to ensure that there are at least two spaces between
3837 these hyphens and the first non-blank character of the comment.
3839 The ``--comments-fill`` switch specifies that whole-line comments
3840 that form a paragraph will be filled in typical word processor style
3841 (that is, moving words between lines to make the lines other than the
3842 last similar in length ).
3844 The ``--comments-only`` switch specifies that only the comments are
3845 formatted; the rest of the program text is left alone. The comments
3846 are formatted according to the ``--comments-gnat-beginning`` and
3847 ``--comments-fill`` switches; other formatting switches are ignored. For
3848 example, ``--comments-only --comments-fill`` means to fill comment
3849 paragraphs, and do nothing else. Likewise, ``--comments-only
3850 --comments-gnat-beginning`` ensures comments start with at least two
3851 spaces after ``--``, and ``--comments-only --comments-gnat-beginning
3852 --comments-fill`` does both. If ``--comments-only`` is given without
3853 ``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp
3854 doesn't format anything.
3862 ``gnatpp`` always converts the usage occurrence of a (simple) name to
3863 the same casing as the corresponding defining identifier.
3865 You control the casing for defining occurrences via the ``--name...``
3866 switches. With ``--name-case-as-declared``, which is the default,
3867 defining occurrences appear exactly as in the source file where they
3868 are declared. The other values for this switch --
3869 ``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
3870 -- result in upper, lower, or mixed case, respectively. If
3871 ``gnatpp`` changes the casing of a defining occurrence, it
3872 analogously changes the casing of all the usage occurrences of this
3875 If the defining occurrence of a name is not in the source compilation
3876 unit currently being processed by ``gnatpp``, the casing of each
3877 reference to this name is changed according to the switch (subject to
3878 the dictionary file mechanism described below). Thus ``gnatpp`` acts
3879 as though the switch had affected the casing for the defining
3880 occurrence of the name.
3883 :switch:`--attribute...`,
3884 :switch:`--keyword...`,
3885 :switch:`--enum...`,
3886 :switch:`--type...`,
3887 :switch:`--number...`, and
3888 :switch:`--pragma...`
3889 allow finer-grained control over casing for
3890 attributes, keywords, enumeration literals,
3891 types, named numbers and pragmas, respectively.
3892 :switch:`--type...` cover subtypes as well.
3894 Some names may need to be spelled with casing conventions that are not
3895 covered by the upper-, lower-, and mixed-case transformations.
3896 You can arrange correct casing by placing such names in a
3898 and then supplying a ``--dictionary`` switch.
3899 The casing of names from dictionary files overrides
3900 any ``--name...`` switch.
3902 To handle the casing of Ada predefined names and the names from GNAT libraries,
3903 ``gnatpp`` assumes a default dictionary file.
3904 The name of each predefined entity is spelled with the same casing as is used
3905 for the entity in the :title:`Ada Reference Manual` (usually mixed case).
3906 The name of each entity in the GNAT libraries is spelled with the same casing
3907 as is used in the declaration of that entity.
3909 The ``--dictionary=-`` switch suppresses the use of
3910 the default dictionary file. Instead, the casing for predefined and
3911 GNAT-defined names will be established by the
3912 ``-n`` switch or explicit dictionary files. For
3913 example, by default the names ``Ada.Text_IO`` and
3914 ``GNAT.OS_Lib`` will appear as just shown, even in the presence of
3915 a ``--name-upper-case`` switch. To ensure that even
3916 such names are rendered in uppercase, additionally supply the
3917 --dictionary=- switch (or else place these names
3918 in upper case in a dictionary file).
3920 A dictionary file is a plain text file; each line in this file can be
3921 either a blank line (containing only space characters), an Ada comment
3922 line, or the specification of exactly one *casing schema*.
3924 A casing schema is a string that has the following syntax:
3928 casing_schema ::= identifier | simple_identifier
3930 simple_identifier ::= letter{letter_or_digit}
3933 (See :title:`Ada Reference Manual`, Section 2.3) for the definition of the
3934 ``identifier`` lexical element and the ``letter_or_digit`` category.)
3936 The casing schema string can be followed by white space and/or an Ada-style
3937 comment; any amount of white space is allowed before the string.
3939 If a dictionary file is passed as
3940 the value of a :switch:`--dictionary={file}` switch
3942 simple name and every identifier, ``gnatpp`` checks if the dictionary
3943 defines the casing for the name or for some of its parts (the term 'subword'
3944 is used below to denote the part of a name which is delimited by '_' or by
3945 the beginning or end of the word and which does not contain any '_' inside):
3947 * if the whole name is in the dictionary, ``gnatpp`` uses for this name
3948 the casing defined by the dictionary; no subwords are checked for this word
3950 * for every subword ``gnatpp`` checks if the dictionary contains the
3951 corresponding string of the form ``simple_identifier``,
3952 and if it does, the casing of this ``simple_identifier`` is used
3955 * if the whole name does not contain any '_' inside, and if for this name
3956 the dictionary contains two entries -- one of the form ``identifier``,
3957 and another of the form ``simple_identifier`` -- then the first one
3958 is applied to define the casing of this name
3960 * if more than one dictionary file is passed as ``gnatpp`` switches, each
3961 dictionary adds new casing exceptions and overrides all the existing casing
3962 exceptions set by the previous dictionaries
3964 * when ``gnatpp`` checks if the word or subword is in the dictionary,
3965 this check is not case sensitive
3967 For example, suppose we have the following source to reformat:
3972 name1 : integer := 1;
3973 name4_name3_name2 : integer := 2;
3974 name2_name3_name4 : Boolean;
3977 name2_name3_name4 := name4_name3_name2 > name1;
3980 And suppose we have two dictionaries:
3992 If ``gnatpp`` is called with the following switches:
3996 $ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb
3998 then we will get the following name casing in the ``gnatpp`` output:
4004 NAME1 : Integer := 1;
4005 Name4_NAME3_Name2 : Integer := 2;
4006 Name2_NAME3_Name4 : Boolean;
4009 Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
4012 .. _Preprocessor_directives:
4014 Preprocessor Directives
4015 ^^^^^^^^^^^^^^^^^^^^^^^
4017 ``gnatpp`` has some support for preprocessor directives.
4018 You can use preprocessor symbols, as in ``$symbol``.
4019 In addition, you can use conditional compilation,
4020 so long as the program text is syntactically legal Ada code
4021 after removing all the preprocessor directives (lines starting
4022 with ``#``). For example, ``gnatpp`` can format the following:
4028 X : constant Integer := 123;
4030 X : constant Integer := 456;
4034 which will be formatted as if it were:
4039 X : constant Integer := 123;
4040 X : constant Integer := 456;
4043 except that the ``#`` lines will be preserved.
4044 However, ``gnatpp`` cannot format the following:
4059 because removing the ``#`` lines gives:
4071 which is not syntactically legal.
4076 Some switches have a short form, mostly for legacy reasons,
4079 .. index:: -n (gnatpp)
4082 :switch:`--name-case-as-declared`
4085 :switch:`--name-upper-case`
4088 :switch:`--name-lower-case`
4091 :switch:`--name-mixed-case`
4093 .. index:: -a (gnatpp)
4096 :switch:`--attribute-lower-case`
4099 :switch:`--attribute-upper-case`
4102 :switch:`--attribute-mixed-case`
4104 .. index:: -k (gnatpp)
4107 :switch:`--keyword-lower-case`
4110 :switch:`--keyword-upper-case`
4112 .. index:: -ne (gnatpp)
4115 :switch:`--enum-case-as-declared`
4118 :switch:`--enum-upper-case`
4121 :switch:`--enum-lower-case`
4124 :switch:`--enum-mixed-case`
4126 .. index:: -nt (gnatpp)
4129 :switch:`--type-case-as-declared`
4132 :switch:`--type-upper-case`
4135 :switch:`--type-lower-case`
4138 :switch:`--type-mixed-case`
4141 :switch:`--number-upper-case`
4144 :switch:`--number-lower-case`
4147 :switch:`--number-mixed-case`
4149 .. index:: -p (gnatpp)
4152 :switch:`--pragma-lower-case`
4155 :switch:`--pragma-upper-case`
4158 :switch:`--pragma-mixed-case`
4160 .. index:: -D (gnatpp)
4163 :switch:`--dictionary={file}`
4165 .. index:: -D- (gnatpp)
4168 :switch:`--dictionary=-`
4170 .. index:: -c (gnatpp)
4173 :switch:`--comments-unchanged`
4176 :switch:`--comments-gnat-indentation`
4179 :switch:`--comments-gnat-beginning`
4182 :switch:`--comments-fill`
4185 :switch:`--comments-special`
4187 .. index:: -M (gnatpp)
4190 :switch:`--max-line-length={nnn}`
4192 .. index:: -i (gnatpp)
4195 :switch:`--indentation={nnn}`
4197 .. index:: -cl (gnatpp)
4200 :switch:`--indent-continuation={nnn}`
4202 .. index:: -pipe (gnatpp)
4207 .. index:: -o (gnatpp)
4209 :switch:`-o {output-file}`
4210 :switch:`--output={output-file}`
4212 .. index:: -of (gnatpp)
4214 :switch:`-of {output-file}`
4215 :switch:`--output-force={output-file}`
4217 .. index:: -r (gnatpp)
4223 :switch:`--replace-backup`
4225 .. index:: -rf (gnatpp)
4228 :switch:`--replace-force-backup`
4230 .. index:: -rnb (gnatpp)
4232 .. index:: --eol (gnatpp)
4234 .. index:: -W (gnatpp)
4237 :switch:`--wide-character-encoding={e}`
4239 .. index:: -files (gnatpp)
4241 :switch:`-files {filename}`
4242 :switch:`--files={filename}`
4244 .. index:: -j (gnatpp)
4247 :switch:`--jobs={n}`
4249 .. index:: -v (gnatpp)
4254 .. index:: -q (gnatpp)
4260 .. only:: PRO or GPL
4262 .. _The_Body_Stub_Generator_gnatstub:
4264 The Body Stub Generator *gnatstub*
4265 ==================================
4267 .. index:: ! gnatstub
4269 ``gnatstub`` creates empty but compilable bodies
4270 for library unit declarations, and empty but compilable
4271 subunits for body stubs.
4273 ``gnatstub`` is a project-aware tool.
4274 (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
4275 the project-related switches but note that ``gnatstub`` does not support
4276 the :switch:`-U`, :switch:`-U {main_unit}`, :switch:`--subdirs={dir}`, or
4277 :switch:`--no-objects-dir` switches.)
4278 The project file package that can specify
4279 ``gnatstub`` switches is named ``gnatstub``.
4282 By default, all the program unit bodies generated by ``gnatstub``
4283 raise ``Program_Error``, which will catch accidental calls of
4284 generated stubs. This behavior can be changed with option
4285 ``--no-exception`` (see below).
4287 .. _Running_gnatstub:
4289 Running ``gnatstub``
4290 --------------------
4292 ``gnatstub`` invocation has the following form:
4296 $ gnatstub [ switches ] {filename}
4301 is the name of the source file that contains a library unit declaration
4302 for which a body must be created or a library unit body for which subunits
4303 must be created for the body stubs declared in this body.
4304 The file name may contain path information.
4305 If the name does not follow GNAT file naming conventions and the set
4306 of switches does not contain a project file that defines naming
4307 conventions, the name of the body file must
4309 explicitly as the value of the :switch:`--output={body-name}` option.
4310 If the file name follows the GNAT file naming
4311 conventions and the name of the body file is not provided,
4313 takes the naming conventions for the generated source from the
4314 project file provided as a parameter of ``-P`` switch if any,
4315 or creates the name file to generate using the standard GNAT
4318 Note that it is no longer necessary to specify the Ada language version;
4319 ``gnatmetric`` can process Ada source code written in any version from
4320 Ada 83 onward without specifying any language version switch.
4323 is an optional sequence of switches as described in the next section
4326 .. _Switches_for_gnatstub:
4328 Switches for ``gnatstub``
4329 -------------------------
4331 .. index:: --version (gnatstub)
4334 Display copyright and version, then exit disregarding all other options.
4337 .. index:: --help (gnatstub)
4340 Display usage, then exit disregarding all other options.
4343 .. index:: -P (gnatstub)
4346 Indicates the name of the project file that describes the set of sources
4347 to be processed. An aggregate project is allowed as the file parameter only
4348 if it has exactly one non-aggregate project being aggregated.
4351 .. index:: -X (gnatstub)
4353 :switch:`-X{name}={value}`
4354 Indicates that external variable ``name`` in the argument project
4355 has the value ``value``. Has no effect if no project is specified.
4358 .. index:: --RTS (gnatstub)
4360 :switch:`--RTS={rts-path}`
4361 Specifies the default location of the runtime library. Same meaning as the
4362 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
4365 .. index:: --subunits (gnatstub)
4367 :switch:`--subunits`
4368 Generate subunits for body stubs. If this switch is specified,
4369 ``gnatstub`` expects a library unit body as an argument file;
4370 otherwise a library unit declaration is expected. If a body stub
4371 already has a corresponding subunit, ``gnatstub`` does not
4372 generate anything for it.
4375 .. index:: --force (gnatstub)
4378 If the destination directory already contains a file with the name of the
4380 for the argument spec file, replace it with the generated body stub.
4381 This switch cannot be used together with ``--subunits``.
4384 .. index:: --comment-header-spec (gnatstub)
4386 :switch:`--comment-header-spec`
4387 Put the comment header (i.e., all the comments preceding the
4388 compilation unit) from the source of the library unit declaration
4392 .. index:: --comment-header-sample (gnatstub)
4394 :switch:`--comment-header-sample`
4395 Put a sample comment header into the body stub.
4398 .. index:: --header-file (gnatstub)
4400 :switch:`--header-file={filename}`
4401 Use the content of the file as the comment header for a generated body stub.
4404 .. index:: --max-line-length (gnatstub)
4406 :switch:`--max-line-length={n}`
4407 (``n`` is a non-negative integer). Set the maximum line length for
4408 the output files. The default is 79. The maximum value that can be
4412 .. index:: --indentation (gnatstub)
4414 :switch:`--indentation={n}`
4415 (``n`` is an integer from 1 to 9). Set the indentation level in
4416 the generated files to ``n``.
4417 The default indentation is 3.
4420 .. index:: --alphabetical-order (gnatstub)
4422 :switch:`--alphabetical-order`
4423 Order local bodies alphabetically. (By default local bodies are ordered
4424 in the same way as the corresponding local specs in the argument
4428 .. index:: --no-exception (gnatstub)
4430 :switch:`--no-exception`
4431 Avoid raising Program_Error in the generated bodies of program unit stubs,
4432 except in the case of functions, where we have no value to return.
4435 .. index:: --no-local-header (gnatstub)
4437 :switch:`--no-local-header`
4438 Do not place local comment header with unit name before body stub for a
4442 .. index:: --files (gnatstub)
4444 :switch:`--files={filename}`
4445 Take as arguments the files listed in text file ``file``.
4446 Text file ``file`` may contain empty lines that are ignored.
4447 Each nonempty line should contain the name of an existing file.
4448 Several such switches may be specified.
4451 .. index:: --output (gnatstub)
4453 :switch:`--output={body-name}`
4454 Body file name. This should be set if the argument file name does
4455 not follow the default GNAT file naming conventions, and the naming
4456 conventions are not specified by a project file. If this switch and
4457 ``-P`` are both omitted, the name for the body will be obtained
4458 according to the default GNAT file naming conventions.
4461 .. index:: --output-dir (gnatstub)
4463 :switch:`--output-dir={dir-name}`
4464 The directory in which to place the output files.
4465 If this switch is not set, the generated library unit body is
4466 placed in the current directory, and generated sununits
4467 in the directory where the argument body is located.
4470 .. index:: --wide-character-encoding (gnatstub)
4472 :switch:`--wide-character-encoding={e}`
4473 Specify the wide character encoding method for the input and output
4474 files. ``e`` is one of the following:
4476 * *8* - UTF-8 encoding
4478 * *b* - Brackets encoding (default value)
4481 .. index:: --quiet (gnatstub)
4482 .. index:: -q (gnatstub)
4484 :switch:`--quiet` / :switch:`-q`
4488 .. index:: --verbose (gnatstub)
4489 .. index:: -v (gnatstub)
4491 :switch:`--verbose` / :switch:`-v`
4497 Some switches have a short form, mostly for legacy reasons,
4500 .. index:: -M (gnatstub)
4502 :switch:`-gnatyM{nnn}`
4503 :switch:`--max-line-length={nnn}`
4505 .. index:: -i (gnatstub)
4508 :switch:`--indentation={nnn}`
4510 .. index:: -gnaty (gnatstub)
4512 :switch:`-gnaty{nnn}`
4513 :switch:`--indentation={nnn}`
4515 .. index:: -f (gnatstub)
4520 .. index:: -gnatyo (gnatstub)
4523 :switch:`--alphabetical-order`
4525 .. index:: -hg (gnatstub)
4528 :switch:`--comment-header-sample`
4530 .. index:: -hs (gnatstub)
4533 :switch:`--comment-header-spec`
4535 .. index:: -o (gnatstub)
4537 :switch:`-o {output-file}`
4538 :switch:`--output={output-file}`
4540 .. index:: -dir (gnatstub)
4542 :switch:`-dir {dir-name}`
4543 :switch:`--output-dir={dir-name}`
4545 .. index:: -W (gnatstub)
4548 :switch:`--wide-character-encoding={e}`
4550 .. index:: -files (gnatstub)
4552 :switch:`-files {filename}`
4553 :switch:`--files={filename}`
4556 .. only:: PRO or GPL
4558 .. _The_Unit_Test_Generator_gnattest:
4560 The Unit Test Generator ``gnattest``
4561 ====================================
4563 .. index:: ! gnattest
4565 ``gnattest`` is an ASIS-based utility that creates unit-test skeletons
4566 as well as a test driver infrastructure (harness). ``gnattest`` creates
4567 a skeleton for each visible subprogram in the packages under consideration when
4568 they do not exist already.
4570 ``gnattest`` is a project-aware tool.
4571 (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
4572 the project-related switches but note that ``gnattest`` does not support
4573 the :switch:`-U`, :switch:`-eL`, :switch:`--subdirs={dir}`, or
4574 :switch:`--no-objects-dir` switches.)
4575 The project file package that can specify
4576 ``gnattest`` switches is named ``gnattest``.
4578 The user can choose to generate a single test driver
4579 that will run all individual tests, or separate test drivers for each test. The
4580 second option allows much greater flexibility in test execution environment,
4581 allows to benefit from parallel tests execution to increase performance, and
4582 provides stubbing support.
4584 ``gnattest`` also has a mode of operation where it acts as the test
4585 aggregator when multiple test executables must be run, in particular when
4586 the separate test drivers were generated. In this mode it handles individual
4587 tests execution and upon completion reports the summary results of the test
4590 In order to process source files from a project, ``gnattest`` has to
4591 semantically analyze the sources. Therefore, test skeletons can only be
4592 generated for legal Ada units. If a unit is dependent on other units,
4593 those units should be among the source files of the project or of other projects
4594 imported by this one.
4596 Generated skeletons and harnesses are based on the AUnit testing framework.
4597 AUnit is an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit
4598 for Java or CppUnit for C++. While it is advised that gnattest users read
4599 the AUnit manual, deep knowledge of AUnit is not necessary for using ``gnattest``.
4600 For correct operation of ``gnattest``, AUnit should be installed and
4601 aunit.gpr must be on the project path. Except for some special circumstances
4602 (e.g. a custom run-time is used), this should normally be the case out of the box.
4605 .. _Running_gnattest:
4607 Running ``gnattest``
4608 --------------------
4610 There are two ways of running ``gnattest``.
4612 .. _Framework_Generation_Mode:
4614 Framework Generation Mode
4615 ^^^^^^^^^^^^^^^^^^^^^^^^^
4617 In this mode ``gnattest`` has the following command-line interface:
4621 $ gnattest -Pprojname [ switches ] [ filename ] [ -cargs gcc_switches ]
4625 * :switch:`-P{projname}`
4626 specifies the project defining the location of source files. When no
4627 file names are provided on the command line, all sources in the project
4628 are used as input. This switch is required.
4630 * :switch:`{filename}`
4631 is the name of the source file containing the library unit package *declaration*
4632 (the package "spec") for which a test package will be created. The file name
4633 may be given with a path.
4635 * :samp:`{switches}`
4636 is an optional sequence of switches as described below.
4638 * :samp:`{gcc_switches}`
4639 is a list of additional switches for
4640 ``gcc`` that will be passed to all compiler invocations
4641 made by ``gnattest`` to generate a set of ASIS trees.
4644 ``gnattest`` results can be found in two different places.
4646 * *automatic harness*:
4647 This is the harness code, which is located by default in
4648 "gnattest/harness" directory created in the object directory of
4649 the main project file. All of this code is generated completely
4650 automatically and can be destroyed and regenerated at will, with the
4651 exception of the file *gnattest_common.gpr*, which is created if absent,
4652 but never overwritten. It is not recommended to modify other files
4653 manually, since these modifications will be lost if ``gnattest`` is re-run.
4654 The entry point in the harness code is
4655 the project file named *test_driver.gpr*. Tests can be compiled and run
4656 using a command such as:
4660 $ gprbuild -P<harness-dir>/test_driver
4662 Note that if you need to adjust any options used to compile the harness,
4663 you can do so by editing the file *gnattest_common.gpr*.
4665 * *actual unit test skeletons*:
4666 A test skeleton for each visible subprogram is created in a separate file, if it
4667 doesn't exist already. By default, those separate test files are located in a
4668 "gnattest/tests" directory that is created in the object directory of
4669 corresponding project file. For example, if a source file my_unit.ads in
4670 directory src contains a visible subprogram Proc, then the corresponding unit
4671 test will be found in file src/tests/my_unit-test_data-tests.adb and will be
4672 called Test_Proc_<code>. <code> is a signature encoding used to differentiate
4673 test names in case of overloading.
4675 Note that if the project already has both my_unit.ads and my_unit-test_data.ads,
4676 this will cause a name conflict with the generated test package.
4679 .. _Test_Execution_Mode:
4684 In this mode ``gnattest`` has a the following command-line interface:
4688 $ gnattest test_drivers.list [ switches ]
4692 * :samp:`{test_drivers.list}`
4693 is the name of the text file containing the list of executables to treat as
4694 test drivers. This file is automatically generated by gnattest, but can be
4695 hand-edited to add or remove tests. This switch is required.
4698 * :samp:`{switches}`
4699 is an optional sequence of switches as described below.
4702 .. _Switches_for_gnattest_in_framework_generation_mode:
4704 Switches for ``gnattest`` in framework generation mode
4705 ------------------------------------------------------
4707 .. index:: --strict (gnattest)
4710 Return error exit code if there are any compilation errors.
4712 .. index:: -q (gnattest)
4715 Quiet mode: suppresses noncritical output messages.
4718 .. index:: -v (gnattest)
4721 Verbose mode: produces additional output about the execution of the tool.
4722 When specified alone on the command line, prints tool version and exits.
4725 .. index:: -r (gnattest)
4728 Recursively considers all sources from all projects.
4730 .. index:: -files (gnattest)
4732 :switch:`-files={filename}`
4733 Take as arguments the files listed in text file ``file``.
4734 Text file ``file`` may contain empty lines that are ignored.
4735 Each nonempty line should contain the name of an existing file.
4736 Several such switches may be specified simultaneously.
4738 .. index:: --ignore (gnattest)
4740 :switch:`--ignore={filename}`
4741 Do not process the sources listed in a specified file.
4743 .. index:: --RTS (gnattest)
4745 :switch:`--RTS={rts-path}`
4746 Specifies the default location of the runtime library. Same meaning as the
4747 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). For restricted
4748 profiles, ``gnattest`` takes into account the run-time limitations when
4749 generating the harness.
4752 .. index:: --additional-tests (gnattest)
4754 :switch:`--additional-tests={projname}`
4755 Sources described in ``projname`` are considered potential additional
4756 manual tests to be added to the test suite.
4759 .. index:: --harness-only (gnattest)
4761 :switch:`--harness-only`
4762 When this option is given, ``gnattest`` creates a harness for all
4763 sources, treating them as test packages. This option is not compatible with
4764 closure computation done by -U main.
4767 .. index:: --separate-drivers (gnattest)
4769 :switch:`--separate-drivers[={val}]`
4770 Generates a separate test driver for each test or unit under test, rather
4771 than a single executable incorporating all tests. ``val`` can be "unit" or
4772 "test", or may be omitted, which defaults to "unit".
4775 .. index:: --stub (gnattest)
4778 Generates the testing framework that uses subsystem stubbing to isolate the
4782 .. index:: --harness-dir (gnattest)
4784 :switch:`--harness-dir={dirname}`
4785 Specifies the directory that will hold the harness packages and project file
4786 for the test driver. If the ``dirname`` is a relative path, it is considered
4787 relative to the object directory of the project file.
4790 .. index:: --tests-dir (gnattest)
4792 :switch:`--tests-dir={dirname}`
4793 All test packages are placed in the ``dirname`` directory.
4794 If the ``dirname`` is a relative path, it is considered relative to the object
4795 directory of the project file. When all sources from all projects are taken
4796 recursively from all projects, ``dirname`` directories are created for each
4797 project in their object directories and test packages are placed accordingly.
4800 .. index:: --subdir (gnattest)
4802 :switch:`--subdir={dirname}`
4803 Test packages are placed in a subdirectory of the corresponding source
4804 directory, with the name ``dirname``. Thus, each set of unit tests is located
4805 in a subdirectory of the code under test. If the sources are in separate
4806 directories, each source directory has a test subdirectory named ``dirname``.
4809 .. index:: --tests-root (gnattest)
4811 :switch:`--tests-root={dirname}`
4812 The hierarchy of source directories, if any, is recreated in the ``dirname``
4813 directory, with test packages placed in directories corresponding to those
4815 If the ``dirname`` is a relative path, it is considered relative to the object
4816 directory of the project file. When projects are considered recursively,
4817 directory hierarchies of tested sources are
4818 recreated for each project in their object directories and test packages are
4822 .. index:: --stubs-dir (gnattest)
4824 :switch:`--stubs-dir={dirname}`
4825 The hierarchy of directories containing stubbed units is recreated in
4826 the ``dirname`` directory, with stubs placed in directories corresponding to
4827 projects they are derived from.
4828 If the ``dirname`` is a relative path, it is considered relative to the object
4829 directory of the project file. When projects are considered recursively,
4830 directory hierarchies of stubs are
4831 recreated for each project in their object directories and test packages are
4835 .. index:: --exclude-from-stubbing (gnattest)
4837 :switch:`--exclude-from-stubbing={filename}`
4838 Disables stubbing of units listed in ``filename``. The file should contain
4839 corresponding spec files, one per line.
4841 :switch:`--exclude-from-stubbing:{unit}={filename}`
4842 Same as above, but corresponding units will not be stubbed only when testing
4845 .. index:: --validate-type-extensions (gnattest)
4847 :switch:`--validate-type-extensions`
4848 Enables substitution check: run all tests from all parents in order
4849 to check substitutability in accordance with the Liskov substitution principle (LSP).
4851 .. index:: --inheritance-check (gnattest)
4853 :switch:`--inheritance-check`
4854 Enables inheritance check: run inherited tests against descendants.
4856 .. index:: --no-inheritance-check (gnattest)
4858 :switch:`--no-inheritance-check`
4859 Disables inheritance check.
4861 .. index:: --no-inheritance-check (gnattest)
4863 :switch:`--test-case-only`
4864 Generates test skeletons only for subprograms that have at least one
4865 associated pragma or aspect Test_Case.
4867 .. index:: --skeleton-default (gnattest)
4869 :switch:`--skeleton-default={val}`
4870 Specifies the default behavior of generated skeletons. ``val`` can be either
4871 "fail" or "pass", "fail" being the default.
4874 .. index:: --passed-tests (gnattest)
4876 :switch:`--passed-tests={val}`
4877 Specifies whether or not passed tests should be shown. ``val`` can be either
4878 "show" or "hide", "show" being the default.
4881 .. index:: --exit-status (gnattest)
4883 :switch:`--exit-status={val}`
4884 Specifies whether or not generated test driver should return failure exit
4885 status if at least one test fails or crashes. ``val`` can be either
4886 "on" or "off", "off" being the default.
4889 .. index:: --omit-sloc (gnattest)
4891 :switch:`--omit-sloc`
4892 Suppresses comment line containing file name and line number of corresponding
4893 subprograms in test skeletons.
4896 .. index:: --no-command-line (gnattest)
4898 :switch:`--no-command-line`
4899 Don't add command line support to test driver. Note that regardless of this
4900 switch, ``gnattest`` will automatically refrain from adding command
4901 line support if it detects that the selected run-time doesn't provide
4905 .. index:: --separates (gnattest)
4907 :switch:`--separates`
4908 Bodies of all test routines are generated as separates. Note that this mode is
4909 kept for compatibility reasons only and it is not advised to use it due to
4910 possible problems with hash in names of test skeletons when using an
4911 inconsistent casing. Separate test skeletons can be incorporated to monolith
4912 test package with improved hash being used by using ``--transition``
4916 .. index:: --transition (gnattest)
4918 :switch:`--transition`
4919 This allows transition from separate test routines to monolith test packages.
4920 All matching test routines are overwritten with contents of corresponding
4921 separates. Note that if separate test routines had any manually added with
4922 clauses they will be moved to the test package body as is and have to be moved
4926 .. index:: --test-duration (gnattest)
4928 :switch:`--test-duration`
4929 Adds time measurements for each test in generated test driver.
4932 :switch:`--tests_root`, :switch:`--subdir` and :switch:`--tests-dir` switches are mutually exclusive.
4935 .. _Switches_for_gnattest_in_test_execution_mode:
4937 Switches for ``gnattest`` in test execution mode
4938 ------------------------------------------------
4941 .. index:: --passed-tests (gnattest)
4943 :switch:`--passed-tests={val}`
4944 Specifies whether or not passed tests should be shown. ``val`` can be either
4945 "show" or "hide", "show" being the default.
4948 .. index:: --queues (gnattest)
4949 .. index:: -j (gnattest)
4951 :switch:`--queues={n}`, :switch:`-j{n}`
4952 Runs ``n`` tests in parallel (default is 1).
4955 .. index:: --copy-environment (gnattest)
4957 :switch:`--copy-environment={dir}`
4958 Contents of ``dir`` directory will be copied to temporary directories
4959 created by gnattest in which individual test drivers are spawned.
4962 .. _Project_Attributes_for_gnattest:
4964 Project Attributes for ``gnattest``
4965 -----------------------------------
4967 Most of the command-line options can also be passed to the tool by adding
4968 special attributes to the project file. Those attributes should be put in
4969 package ``Gnattest``. Here is the list of attributes:
4973 is used to select the same output mode as with the ``--tests-root`` option.
4974 This attribute cannot be used together with ``Subdir`` or ``Tests_Dir``.
4977 is used to select the same output mode as with the ``--subdir`` option.
4978 This attribute cannot be used together with ``Tests_Root`` or ``Tests_Dir``.
4981 is used to select the same output mode as with the ``--tests-dir`` option.
4982 This attribute cannot be used together with ``Subdir`` or ``Tests_Root``.
4985 is used to select the same output mode as with the ``--stubs-dir`` option.
4988 is used to specify the directory in which to place harness packages and project
4989 file for the test driver, otherwise specified by ``--harness-dir``.
4991 * ``Additional_Tests``
4992 is used to specify the project file, otherwise given by
4993 ``--additional-tests`` switch.
4995 * ``Skeletons_Default``
4996 is used to specify the default behaviour of test skeletons, otherwise
4997 specified by ``--skeleton-default`` option. The value of this attribute
4998 should be either ``pass`` or ``fail``.
5000 * ``Default_Stub_Exclusion_List``
5001 is used to specify the file with list of units whose bodies should not
5002 be stubbed, otherwise specified by ``--exclude-from-stubbing=filename``.
5004 * ``Stub_Exclusion_List ("unit")``
5005 is used to specify the file with list of units whose bodies should not
5006 be stubbed when testing "unit", otherwise specified by
5007 ``--exclude-from-stubbing:unit=filename``.
5009 Each of those attributes can be overridden from the command line if needed.
5010 Other ``gnattest`` switches can also be passed via the project
5011 file as an attribute list called ``Gnattest_Switches``.
5014 .. _Simple_gnattest_Example:
5019 Let's take a very simple example using the first ``gnattest`` example
5024 <install_prefix>/share/examples/gnattest/simple
5026 This project contains a simple package containing one subprogram. By running ``gnattest``:
5030 $ gnattest --harness-dir=driver -Psimple.gpr
5032 a test driver is created in directory ``driver``. It can be compiled and run:
5037 $ gprbuild -Ptest_driver
5040 One failed test with the diagnosis "test not implemented" is reported.
5041 Since no special output option was specified, the test package ``Simple.Tests``
5046 <install_prefix>/share/examples/gnattest/simple/obj/gnattest/tests
5049 For each package containing visible subprograms, a child test package is
5050 generated. It contains one test routine per tested subprogram. Each
5051 declaration of a test subprogram has a comment specifying which tested
5052 subprogram it corresponds to. Bodies of test routines are placed in test package
5053 bodies and are surrounded by special comment sections. Those comment sections
5054 should not be removed or modified in order for gnattest to be able to regenerate
5055 test packages and keep already written tests in place.
5056 The test routine ``Test_Inc_5eaee3`` located at :file:`simple-test_data-tests.adb` contains
5057 a single statement: a call to procedure ``Assert``. It has two arguments:
5058 the Boolean expression we want to check and the diagnosis message to display if
5059 the condition is false.
5061 That is where actual testing code should be written after a proper setup.
5062 An actual check can be performed by replacing the ``Assert`` call with:
5066 Assert (Inc (1) = 2, "wrong incrementation");
5068 After recompiling and running the test driver, one successfully passed test
5072 .. _Setting_Up_and_Tearing_Down_the_Testing_Environment:
5074 Setting Up and Tearing Down the Testing Environment
5075 ---------------------------------------------------
5077 Besides test routines themselves, each test package has a parent package
5078 ``Test_Data`` that has two procedures: ``Set_Up`` and ``Tear_Down``. This package is never
5079 overwritten by the tool. ``Set_Up`` is called before each test routine of the
5080 package, and ``Tear_Down`` is called after each test routine. Those two procedures
5081 can be used to perform necessary initialization and finalization,
5082 memory allocation, etc. Test type declared in ``Test_Data`` package is parent type
5083 for the test type of test package and can have user-defined components whose
5084 values can be set by ``Set_Up`` routine and used in test routines afterwards.
5087 .. _Regenerating_Tests:
5092 Bodies of test routines and ``Test_Data`` packages are never overridden after they
5093 have been created once. As long as the name of the subprogram, full expanded Ada
5094 names and order of its parameters are the same, and comment sections are
5095 intact, the old test routine will fit in its place and no test skeleton will be
5096 generated for the subprogram.
5098 This can be demonstrated with the previous example. By uncommenting declaration
5099 and body of function Dec in ``simple.ads`` and ``simple.adb``, running
5100 ``gnattest`` on the project, and then running the test driver:
5104 $ gnattest --harness-dir=driver -Psimple.gpr
5106 $ gprbuild -Ptest_driver
5109 The old test is not replaced with a stub, nor is it lost, but a new test
5110 skeleton is created for function ``Dec``.
5112 The only way of regenerating tests skeletons is to remove the previously created
5113 tests together with corresponding comment sections.
5116 .. _Default_Test_Behavior:
5118 Default Test Behavior
5119 ---------------------
5121 The generated test driver can treat unimplemented tests in two ways:
5122 either count them all as failed (this is useful to see which tests are still
5123 left to implement) or as passed (to sort out unimplemented ones from those
5126 The test driver accepts a switch to specify this behavior:
5127 :switch:`--skeleton-default={val}`, where ``val`` is either ``pass`` or ``fail`` (exactly as for
5130 The default behavior of the test driver is set with the same switch
5131 as passed to ``gnattest`` when generating the test driver.
5133 Passing it to the driver generated on the first example:
5137 $ test_runner --skeleton-default=pass
5139 makes both tests pass, even the unimplemented one.
5142 .. _Testing_Primitive_Operations_of_Tagged_Types:
5144 Testing Primitive Operations of Tagged Types
5145 --------------------------------------------
5147 Creation of test skeletons for primitive operations of tagged types entails
5148 a number of features. Test routines for all primitives of a given tagged type
5149 are placed in a separate child package named according to the tagged type. For
5150 example, if you have tagged type ``T`` in package ``P``, all tests for primitives
5151 of ``T`` will be in ``P.T_Test_Data.T_Tests``.
5153 Consider running ``gnattest`` on the second example (note: actual tests for this
5154 example already exist, so there's no need to worry if the tool reports that
5155 no new stubs were generated):
5159 $ cd <install_prefix>/share/examples/gnattest/tagged_rec
5160 $ gnattest --harness-dir=driver -Ptagged_rec.gpr
5162 Taking a closer look at the test type declared in the test package
5163 *Speed1.Controller_Test_Data* is necessary. It is declared in:
5167 <install_prefix>/share/examples/gnattest/tagged_rec/obj/gnattest/tests
5169 Test types are direct or indirect descendants of
5170 *AUnit.Test_Fixtures.Test_Fixture* type. In the case of non-primitive tested
5171 subprograms, the user doesn't need to be concerned with them. However,
5172 when generating test packages for primitive operations, there are some things
5173 the user needs to know.
5175 Type ``Test_Controller`` has components that allow assignment of various
5176 derivations of type ``Controller``. And if you look at the specification of
5177 package *Speed2.Auto_Controller*, you will see that ``Test_Auto_Controller``
5178 actually derives from ``Test_Controller`` rather than AUnit type ``Test_Fixture``.
5179 Thus, test types mirror the hierarchy of tested types.
5181 The ``Set_Up`` procedure of ``Test_Data`` package corresponding to a test package
5182 of primitive operations of type ``T`` assigns to ``Fixture`` a reference to an
5183 object of that exact type ``T``. Note, however, that if the tagged type has
5184 discriminants, the ``Set_Up`` only has a commented template for setting
5185 up the fixture, since filling the discriminant with actual value is up
5188 The knowledge of the structure of test types allows additional testing
5189 without additional effort. Those possibilities are described below.
5192 .. _Testing_Inheritance:
5197 Since the test type hierarchy mimics the hierarchy of tested types, the
5198 inheritance of tests takes place. An example of such inheritance can be
5199 seen by running the test driver generated for the second example. As previously
5200 mentioned, actual tests are already written for this example.
5205 $ gprbuild -Ptest_driver
5208 There are 6 passed tests while there are only 5 testable subprograms. The test
5209 routine for function Speed has been inherited and run against objects of the
5213 .. _Tagged_Type_Substitutability_Testing:
5215 Tagged Type Substitutability Testing
5216 ------------------------------------
5218 *Tagged Type Substitutability Testing* is a way of verifying the global type
5219 consistency by testing. Global type consistency is a principle stating that if
5220 ``S`` is a subtype of ``T`` (in Ada, ``S`` is a derived type of tagged type ``T``),
5221 then objects of type ``T`` may be replaced with objects of type ``S`` (that is,
5222 objects of type ``S`` may be substituted for objects of type ``T``), without
5223 altering any of the desirable properties of the program. When the properties
5224 of the program are expressed in the form of subprogram preconditions and
5225 postconditions (let's call them pre and post), the principle is formulated as
5226 relations between the pre and post of primitive operations and the pre and post
5227 of their derived operations. The pre of a derived operation should not be
5228 stronger than the original pre, and the post of the derived operation should
5229 not be weaker than the original post. Those relations ensure that verifying if
5230 a dispatching call is safe can be done just by using the pre and post of the
5233 Verifying global type consistency by testing consists of running all the unit
5234 tests associated with the primitives of a given tagged type with objects of its
5237 In the example used in the previous section, there was clearly a violation of
5238 type consistency. The overriding primitive ``Adjust_Speed`` in package ``Speed2``
5239 removes the functionality of the overridden primitive and thus doesn't respect
5240 the consistency principle.
5241 ``gnattest`` has a special option to run overridden parent tests against objects
5242 of the type which have overriding primitives:
5246 $ gnattest --harness-dir=driver --validate-type-extensions -Ptagged_rec.gpr
5248 $ gprbuild -Ptest_driver
5251 While all the tests pass by themselves, the parent test for ``Adjust_Speed`` fails
5252 against objects of the derived type.
5254 Non-overridden tests are already inherited for derived test types, so the
5255 ``--validate-type-extensions`` enables the application of overridden tests
5256 to objects of derived types.
5259 .. _Testing_with_Contracts:
5261 Testing with Contracts
5262 ----------------------
5264 ``gnattest`` supports pragmas ``Pre``, ``Post``, and ``Test_Case``,
5265 as well as the corresponding Ada 2012 aspects.
5266 Test routines are generated, one per each ``Test_Case`` associated with a tested
5267 subprogram. Those test routines have special wrappers for tested functions
5268 that have composition of pre- and postcondition of the subprogram with
5269 "requires" and "ensures" of the ``Test_Case`` (depending on the mode, pre and post
5270 either count for ``Nominal`` mode or do *not* count for ``Robustness`` mode).
5272 The third example demonstrates how this works:
5276 $ cd <install_prefix>/share/examples/gnattest/contracts
5277 $ gnattest --harness-dir=driver -Pcontracts.gpr
5279 Putting actual checks within the range of the contract does not cause any
5280 error reports. For example, for the test routine which corresponds to
5285 Assert (Sqrt (9.0) = 3.0, "wrong sqrt");
5287 and for the test routine corresponding to test case 2:
5291 Assert (Sqrt (-5.0) = -1.0, "wrong error indication");
5298 $ gprbuild -Ptest_driver
5301 However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get
5302 a precondition violation for test case one. Also, by using any otherwise
5303 correct but positive pair of numbers in the second test routine, you can also
5304 get a precondition violation. Postconditions are checked and reported
5308 .. _Additional_Tests:
5313 ``gnattest`` can add user-written tests to the main suite of the test
5314 driver. ``gnattest`` traverses the given packages and searches for test
5315 routines. All procedures with a single in out parameter of a type which is
5316 derived from *AUnit.Test_Fixtures.Test_Fixture* and that are declared in package
5317 specifications are added to the suites and are then executed by the test driver.
5318 (``Set_Up`` and ``Tear_Down`` are filtered out.)
5320 An example illustrates two ways of creating test harnesses for user-written
5321 tests. Directory ``additional_tests`` contains an AUnit-based test driver written
5326 <install_prefix>/share/examples/gnattest/additional_tests/
5328 To create a test driver for already-written tests, use the ``--harness-only``
5333 gnattest -Padditional/harness/harness.gpr --harness-dir=harness_only \\
5335 gprbuild -Pharness_only/test_driver.gpr
5336 harness_only/test_runner
5338 Additional tests can also be executed together with generated tests:
5342 gnattest -Psimple.gpr --additional-tests=additional/harness/harness.gpr \\
5343 --harness-dir=mixing
5344 gprbuild -Pmixing/test_driver.gpr
5348 .. _Individual_Test_Drivers:
5350 Individual Test Drivers
5351 -----------------------
5353 By default, ``gnattest`` generates a monolithic test driver that
5354 aggregates the individual tests into a single executable. It is also possible
5355 to generate separate executables for each test or each unit under test, by
5356 passing the switch ``--separate-drivers`` with corresponding parameter. This
5357 approach scales better for large testing campaigns, especially involving target
5358 architectures with limited resources typical for embedded development. It can
5359 also provide a major performance benefit on multi-core systems by allowing
5360 simultaneous execution of multiple tests.
5362 ``gnattest`` can take charge of executing the individual tests; for this,
5363 instead of passing a project file, a text file containing the list of
5364 executables can be passed. Such a file is automatically generated by gnattest
5365 under the name :file:`test_drivers.list`, but it can be
5366 hand-edited to add or remove tests, or replaced. The individual tests can
5367 also be executed standalone, or from any user-defined scripted framework.
5375 Depending on the testing campaign, it is sometimes necessary to isolate the
5376 part of the algorithm under test from its dependencies. This is accomplished
5377 via *stubbing*, i.e. replacing the subprograms that are called from the
5378 subprogram under test by stand-in subprograms that match the profiles of the
5379 original ones, but simply return predetermined values required by the test
5382 This mode of test harness generation is activated by the switch ``--stub``.
5384 The implementation approach chosen by ``gnattest`` is as follows.
5385 For each package under consideration all the packages it is directly depending
5386 on are stubbed, excluding the generic packages and package instantiations.
5387 The stubs are shared for each package under test. The specs of packages to stub
5388 remain intact, while their bodies are replaced, and hide the original bodies by
5389 means of extending projects. Also, for each stubbed
5390 package, a child package with setter routines for each subprogram declaration
5391 is created. These setters are meant to be used to set the behavior of
5392 stubbed subprograms from within test cases.
5394 Note that subprograms belonging to the same package as the subprogram under
5395 test are not stubbed. This guarantees that the sources being tested are
5396 exactly the sources used for production, which is an important property for
5397 establishing the traceability between the testing campaign and production code.
5399 Due to the nature of stubbing process, this mode implies the switch
5400 ``--separate-drivers``, i.e. an individual test driver (with the
5401 corresponding hierarchy of extending projects) is generated for each unit under
5406 Developing a stubs-based testing campaign requires
5407 good understanding of the infrastructure created by ``gnattest`` for
5408 this purpose. We recommend following the two stubbing tutorials
5409 ``simple_stubbing`` and ``advanced_stubbing`` provided
5410 under :file:`<install_prefix>/share/examples/gnattest` before
5411 attempting to use this powerful feature.
5414 .. _Gnatcov_Integration:
5416 Integration with GNATcoverage
5417 -----------------------------
5419 In addition to the harness, ``gnattest`` generates a Makefile. This Makefile
5420 provides targets for building the test drivers and also the targets for
5421 computing the coverage information using GNATcoverage framework when this
5422 coverage analysis tool is available. The target ``coverage`` fully automates
5423 the process: it will first build all test drivers, then run them under
5424 GNATcoverage, analyze individual trace files, and finally aggregate them:
5430 GNATcoverage options, such as coverage criteria and generated report format,
5431 can be adjusted using Makefile variables provided for this purpose.
5433 Note that coverage targets are not generated in the Makefile when
5434 --separate-drivers=test is passed to gnattest.
5437 .. _Putting_Tests_under_Version_Control:
5439 Putting Tests under Version Control
5440 -----------------------------------
5442 As has been stated earlier, ``gnattest`` generates two different types
5443 of code, test skeletons and harness. The harness is generated completely
5444 automatically each time, does not require manual changes and therefore should
5445 not be put under version control.
5446 It makes sense to put under version control files containing test data packages,
5447 both specs and bodies, and files containing bodies of test packages. Note that
5448 test package specs are also generated automatically each time and should not be
5449 put under version control.
5450 Option ``--omit-sloc`` may be useful when putting test packages under version control.
5453 .. _Current_Limitations:
5458 The tool currently has the following limitations:
5460 * generic tests for nested generic packages and their instantiations are
5462 * tests for protected subprograms and entries are not supported;
5463 * pragma ``No_Run_Time`` is not supported;
5464 * pragma ``No_Secondary_Stack`` is not supported;
5465 * if pragmas for interfacing with foreign languages are used, manual
5466 adjustments might be necessary to make the test harness compilable;
5467 * use of some constructs, such as elaboration-control pragmas, Type_Invariant
5468 aspects, and complex variable initializations that use Subprogram'Access,
5469 may result in elaboration circularities in the generated harness.
5472 .. only:: PRO or GPL
5474 .. _The_Backtrace_Symbolizer_gnatsymbolize:
5476 Translating Code Addresses into Source Locations with ``gnatsymbolize``
5477 =======================================================================
5479 .. index:: ! gnatsymbolize
5481 ``gnatsymbolize`` is a program which translates addresses into
5482 their corresponding filename, line number, and function names.
5484 Running ``gnatsymbolize``
5485 -------------------------
5489 $ gnatsymbolize [ switches ] filename [ addresses ]
5491 For instance, consider the following Ada program:
5496 Global_Val : Integer := 0;
5497 procedure Call_Me_First;
5500 with GNAT.IO; use GNAT.IO;
5501 with GNAT.Traceback; use GNAT.Traceback;
5502 with GNAT.Debug_Utilities;
5504 procedure Call_Me_Third is
5505 TB : Tracebacks_Array (1 .. 5);
5508 Global_Val := Global_Val + 1;
5510 Call_Chain (TB, TB_Len);
5511 for K in 1 .. TB_Len loop
5512 Put_Line (GNAT.Debug_Utilities.Image_C (TB (K)));
5516 procedure Call_Me_Second is
5521 procedure Call_Me_First is
5534 This program, when built and run, prints a list of addresses which
5535 correspond to the traceback when inside function ``Call_Me_Third``.
5536 For instance, on x86_64 GNU/Linux:
5540 $ gnatmake -g -q foo.adb
5548 ``gnatsymbolize`` can be used to translate those addresses into
5549 code locations as follow:
5553 $ gnatsymbolize foo 0x0000000000402561 0x00000000004025EF \
5554 0x00000000004025FB 0x0000000000402611 0x00000000004024C7
5555 Pck.Call_Me_Third at pck.adb:12
5556 Pck.Call_Me_Second at pck.adb:20
5557 Pck.Call_Me_First at pck.adb:25
5559 Main at b~foo.adb:184
5561 Switches for ``gnatsymbolize``
5562 ------------------------------
5564 ``gnatsymbolize`` recognizes the following switches:
5566 .. index:: --help (gnatsymbolize)
5569 Display the program's usage, and then exit, disregarding all other
5573 Read the symbolic information from the executable and cache them
5574 in memory in order to accelerate the translation of each address
5575 into a symbolic location.
5577 Depending on the size of the executable and the number of addresses
5578 to translate, this may not always make ``gnatsymbolize`` faster
5582 If :switch:`--cache` is used, dump the contents of the cache on
5583 Standard Output. Has no effect otherwise.
5585 :switch:`--count={N}`
5586 If specified, compute the symbolic traceback ``N`` times in a row.
5587 This option is mostly useful for measuring the performance of
5588 ``gnatsymbolize``, particularly in the case where the cache is
5591 Requirements for Correct Operation
5592 ----------------------------------
5594 The translation is performed by reading the DWARF debugging
5595 information produced by the compiler for each unit. All units
5596 for which the translation is to be done must therefore be compiled
5597 such that DWARF debugging information is produced. In most cases,
5598 this is done by simply compiling with ``-g``.
5600 This program provides a functionality similar to ``addr2line``.
5601 It has fewer options to tailor its output, but has been designed
5602 to require fewer of the DWARF sections to be present in the
5603 executable. In particular, the following sections can be
5604 stripped from the executable without impact to ``gnatsymbolize``'s
5611 .. only:: PRO or GPL
5613 .. _Using_Project_Files_with_GNAT_Tools:
5615 Using Project Files with GNAT Tools
5616 ===================================
5618 This section describes how project files can be used in conjunction
5619 with a number of GNAT tools.
5620 For a comprehensive description of project files and the overall
5621 GNAT Project Manager facility, please refer to the
5622 *GNAT Project Manager* chapter in the
5623 *GPRbuild and GPR Companion Tools User's Guide*.
5625 .. index:: Project-aware tool
5627 If a tool can take a project file as an option and extract the needed
5628 information, such a tool is called a *project-aware* tool.
5630 .. _Switches_Related_to_Project_Files:
5632 Switches Related to Project Files
5633 ---------------------------------
5635 The following switches are used by the project-aware GNAT tools:
5637 :switch:`-P{project_file}`
5638 Indicates the name of the project file whose source files are to
5639 be processed. The exact set of sources depends on other options
5640 specified, see below.
5643 If a project file is supplied, say for project ``proj``,
5644 but no sources are specified for ``proj`` (either by a
5645 project attribute or through a tool option that provides a list
5646 of the files to be used), process all the source files
5647 from projects imported either directly or indirectly by ``proj``.
5648 Otherwise this option has no effect.
5650 :switch:`-U {source_file}`
5651 Similar to :switch:`-U`, but if no sources are specified then
5652 process only those source files for units in the closure of
5653 the Ada source contained in ``source_file``. Note that this option
5654 expects the source file name but not the Ada unit name as its
5657 :switch:`-X{name}={val}`
5658 Indicates that the external variable ``name`` in the project has the
5659 value ``val``. Has no effect if no project has been specified.
5661 :switch:`--subdirs={dir}`
5662 Use the ``dir`` subdirectory of the project's object directory (or the ``dir``
5663 subdirectory of the project file directory if the project does not specify
5664 an object directory) for tool output files. Has no effect if no project
5665 has been specified or if :switch:`--no-objects-dir` is specified.
5667 :switch:`--no-objects-dir`
5668 Place all the result files into the current directory (i.e., the directory
5669 from which the tool invocation command is issued) instead of the project's
5670 object directory. Has no effect if no project has been specified.
5673 Follow all symbolic links when processing project files.
5675 If a project file is specified and there is neither a :switch:`-U` option,
5676 nor a :switch:`-U {main_unit}` option, nor some other explicit option to
5677 specify the source files, then the sources to be processed are the
5678 immediate sources of the specified project (i.e., the source files directly
5679 defined by that project, either implicitly by residing in the project
5680 source directories, or explicitly through any of the source-related
5683 .. _Tool-specific_packages_in_project files:
5685 Tool-specific packages in project files
5686 ---------------------------------------
5688 Each project-aware tool may have a corresponding package in a project file;
5689 the package names are given elsewhere in this manual, in the sections that describe
5690 the respective tools.
5692 A tool-specific package in a project file may define the ``Default_Switches``
5693 attribute indexed by "ada" (as language name). The value of this attribute
5694 is a list of switches that will be supplied at tool invocation.
5695 Project-specific switches cannot be specified through this attribute.