Debian Codegraph @

gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst

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