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_GNAT_Pretty_Printer_gnatpp`
18 * :ref:`The_Body_Stub_Generator_gnatstub`
19 * :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
20
21 It also describes how several of these tools can be used in conjunction
22 with project files: :ref:`Using_Project_Files_with_GNAT_Tools`
23
24 .. only:: FSF
25
26 * :ref:`The_File_Cleanup_Utility_gnatclean`
27 * :ref:`The_GNAT_Library_Browser_gnatls`
28
29 Other GNAT utilities are described elsewhere in this manual:
30
31 * :ref:`Handling_Arbitrary_File_Naming_Conventions_with_gnatname`
32 * :ref:`File_Name_Krunching_with_gnatkr`
33 * :ref:`Renaming_Files_with_gnatchop`
34 * :ref:`Preprocessing_with_gnatprep`
35
36
37 .. _The_File_Cleanup_Utility_gnatclean:
38
39 The File Cleanup Utility ``gnatclean``
40 ======================================
41
42 .. index:: File cleanup tool
43 .. index:: gnatclean
44
45 ``gnatclean`` is a tool that allows the deletion of files produced by the
46 compiler, binder and linker, including ALI files, object files, tree files,
47 expanded source files, library files, interface copy source files, binder
48 generated files and executable files.
49
50 .. _Running_gnatclean:
51
52 Running ``gnatclean``
53 ---------------------
54
55 The ``gnatclean`` command has the form:
56
57 ::
58
59 $ gnatclean switches names
60
61 where ``names`` is a list of source file names. Suffixes :file:`.ads` and
62 :file:`adb` may be omitted. If a project file is specified using switch
63 :switch:`-P`, then ``names`` may be completely omitted.
64
65 In normal mode, ``gnatclean`` delete the files produced by the compiler and,
66 if switch :switch:`-c` is not specified, by the binder and
67 the linker. In informative-only mode, specified by switch
68 :switch:`-n`, the list of files that would have been deleted in
69 normal mode is listed, but no file is actually deleted.
70
71
72 .. _Switches_for_gnatclean:
73
74 Switches for ``gnatclean``
75 --------------------------
76
77 ``gnatclean`` recognizes the following switches:
78
79 .. index:: --version (gnatclean)
80
81 :switch:`--version`
82 Display copyright and version, then exit disregarding all other options.
83
84 .. index:: --help (gnatclean)
85
86 :switch:`--help`
87 If :switch:`--version` was not used, display usage, then exit disregarding
88 all other options.
89
90 :switch:`--subdirs={subdir}`
91 Actual object directory of each project file is the subdirectory subdir of the
92 object directory specified or defaulted in the project file.
93
94 :switch:`--unchecked-shared-lib-imports`
95 By default, shared library projects are not allowed to import static library
96 projects. When this switch is used on the command line, this restriction is
97 relaxed.
98
99 .. index:: -c (gnatclean)
100
101 :switch:`-c`
102 Only attempt to delete the files produced by the compiler, not those produced
103 by the binder or the linker. The files that are not to be deleted are library
104 files, interface copy files, binder generated files and executable files.
105
106 .. index:: -D (gnatclean)
107
108 :switch:`-D {dir}`
109 Indicate that ALI and object files should normally be found in directory ``dir``.
110
111 .. index:: -F (gnatclean)
112
113 :switch:`-F`
114 When using project files, if some errors or warnings are detected during
115 parsing and verbose mode is not in effect (no use of switch
116 -v), then error lines start with the full path name of the project
117 file, rather than its simple file name.
118
119 .. index:: -h (gnatclean)
120
121 :switch:`-h`
122 Output a message explaining the usage of ``gnatclean``.
123
124 .. index:: -n (gnatclean)
125
126 :switch:`-n`
127 Informative-only mode. Do not delete any files. Output the list of the files
128 that would have been deleted if this switch was not specified.
129
130 .. index:: -P (gnatclean)
131
132 :switch:`-P{project}`
133 Use project file ``project``. Only one such switch can be used.
134 When cleaning a project file, the files produced by the compilation of the
135 immediate sources or inherited sources of the project files are to be
136 deleted. This is not depending on the presence or not of executable names
137 on the command line.
138
139 .. index:: -q (gnatclean)
140
141 :switch:`-q`
142 Quiet output. If there are no errors, do not output anything, except in
143 verbose mode (switch -v) or in informative-only mode
144 (switch -n).
145
146 .. index:: -r (gnatclean)
147
148 :switch:`-r`
149 When a project file is specified (using switch -P),
150 clean all imported and extended project files, recursively. If this switch
151 is not specified, only the files related to the main project file are to be
152 deleted. This switch has no effect if no project file is specified.
153
154 .. index:: -v (gnatclean)
155
156 :switch:`-v`
157 Verbose mode.
158
159 .. index:: -vP (gnatclean)
160
161 :switch:`-vP{x}`
162 Indicates the verbosity of the parsing of GNAT project files.
163 :ref:`Switches_Related_to_Project_Files`.
164
165 .. index:: -X (gnatclean)
166
167 :switch:`-X{name}={value}`
168 Indicates that external variable ``name`` has the value ``value``.
169 The Project Manager will use this value for occurrences of
170 ``external(name)`` when parsing the project file.
171 See :ref:`Switches_Related_to_Project_Files`.
172
173 .. index:: -aO (gnatclean)
174
175 :switch:`-aO{dir}`
176 When searching for ALI and object files, look in directory ``dir``.
177
178 .. index:: -I (gnatclean)
179
180 :switch:`-I{dir}`
181 Equivalent to :switch:`-aO{dir}`.
182
183 .. index:: -I- (gnatclean)
184
185 .. index:: Source files, suppressing search
186
187 :switch:`-I-`
188 Do not look for ALI or object files in the directory
189 where ``gnatclean`` was invoked.
190
191
192
193 .. _The_GNAT_Library_Browser_gnatls:
194
195 The GNAT Library Browser ``gnatls``
196 ===================================
197
198 .. index:: Library browser
199 .. index:: ! gnatls
200
201 ``gnatls`` is a tool that outputs information about compiled
202 units. It gives the relationship between objects, unit names and source
203 files. It can also be used to check the source dependencies of a unit
204 as well as various characteristics.
205
206 .. _Running_gnatls:
207
208 Running ``gnatls``
209 ------------------
210
211 The ``gnatls`` command has the form
212
213 ::
214
215 $ gnatls switches object_or_ali_file
216
217 The main argument is the list of object or :file:`ali` files
218 (see :ref:`The_Ada_Library_Information_Files`)
219 for which information is requested.
220
221 In normal mode, without additional option, ``gnatls`` produces a
222 four-column listing. Each line represents information for a specific
223 object. The first column gives the full path of the object, the second
224 column gives the name of the principal unit in this object, the third
225 column gives the status of the source and the fourth column gives the
226 full path of the source representing this unit.
227 Here is a simple example of use:
228
229
230 ::
231
232 $ gnatls *.o
233 ./demo1.o demo1 DIF demo1.adb
234 ./demo2.o demo2 OK demo2.adb
235 ./hello.o h1 OK hello.adb
236 ./instr-child.o instr.child MOK instr-child.adb
237 ./instr.o instr OK instr.adb
238 ./tef.o tef DIF tef.adb
239 ./text_io_example.o text_io_example OK text_io_example.adb
240 ./tgef.o tgef DIF tgef.adb
241
242 The first line can be interpreted as follows: the main unit which is
243 contained in
244 object file :file:`demo1.o` is demo1, whose main source is in
245 :file:`demo1.adb`. Furthermore, the version of the source used for the
246 compilation of demo1 has been modified (DIF). Each source file has a status
247 qualifier which can be:
248
249 *OK (unchanged)*
250 The version of the source file used for the compilation of the
251 specified unit corresponds exactly to the actual source file.
252
253 *MOK (slightly modified)*
254 The version of the source file used for the compilation of the
255 specified unit differs from the actual source file but not enough to
256 require recompilation. If you use gnatmake with the option
257 :switch:`-m` (minimal recompilation), a file marked
258 MOK will not be recompiled.
259
260 *DIF (modified)*
261 No version of the source found on the path corresponds to the source
262 used to build this object.
263
264 *??? (file not found)*
265 No source file was found for this unit.
266
267 *HID (hidden, unchanged version not first on PATH)*
268 The version of the source that corresponds exactly to the source used
269 for compilation has been found on the path but it is hidden by another
270 version of the same source that has been modified.
271
272
273 .. _Switches_for_gnatls:
274
275 Switches for ``gnatls``
276 -----------------------
277
278 ``gnatls`` recognizes the following switches:
279
280
281 .. index:: --version (gnatls)
282
283 :switch:`--version`
284 Display copyright and version, then exit disregarding all other options.
285
286
287 .. index:: --help (gnatls)
288
289 :switch:`--help`
290 If :switch:`--version` was not used, display usage, then exit disregarding
291 all other options.
292
293
294 .. index:: -a (gnatls)
295
296 :switch:`-a`
297 Consider all units, including those of the predefined Ada library.
298 Especially useful with :switch:`-d`.
299
300
301 .. index:: -d (gnatls)
302
303 :switch:`-d`
304 List sources from which specified units depend on.
305
306
307 .. index:: -h (gnatls)
308
309 :switch:`-h`
310 Output the list of options.
311
312
313 .. index:: -o (gnatls)
314
315 :switch:`-o`
316 Only output information about object files.
317
318
319 .. index:: -s (gnatls)
320
321 :switch:`-s`
322 Only output information about source files.
323
324
325 .. index:: -u (gnatls)
326
327 :switch:`-u`
328 Only output information about compilation units.
329
330
331 .. index:: -files (gnatls)
332
333 :switch:`-files={file}`
334 Take as arguments the files listed in text file ``file``.
335 Text file ``file`` may contain empty lines that are ignored.
336 Each nonempty line should contain the name of an existing file.
337 Several such switches may be specified simultaneously.
338
339
340 .. index:: -aO (gnatls)
341
342 .. index:: -aI (gnatls)
343
344 .. index:: -I (gnatls)
345
346 .. index:: -I- (gnatls)
347
348 :switch:`-aO{dir}`, :switch:`-aI{dir}`, :switch:`-I{dir}`, :switch:`-I-`, :switch:`-nostdinc`
349 Source path manipulation. Same meaning as the equivalent ``gnatmake``
350 flags (:ref:`Switches_for_gnatmake`).
351
352
353 .. index:: -aP (gnatls)
354
355 :switch:`-aP{dir}`
356 Add ``dir`` at the beginning of the project search dir.
357
358
359 .. index:: --RTS (gnatls)
360
361 :switch:`--RTS={rts-path}`
362 Specifies the default location of the runtime library. Same meaning as the
363 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
364
365
366 .. index:: -v (gnatls)
367
368 :switch:`-v`
369 Verbose mode. Output the complete source, object and project paths. Do not use
370 the default column layout but instead use long format giving as much as
371 information possible on each requested units, including special
372 characteristics such as:
373
374 * *Preelaborable*: The unit is preelaborable in the Ada sense.
375
376 * *No_Elab_Code*: No elaboration code has been produced by the compiler for this unit.
377
378 * *Pure*: The unit is pure in the Ada sense.
379
380 * *Elaborate_Body*: The unit contains a pragma Elaborate_Body.
381
382 * *Remote_Types*: The unit contains a pragma Remote_Types.
383
384 * *Shared_Passive*: The unit contains a pragma Shared_Passive.
385
386 * *Predefined*: This unit is part of the predefined environment and cannot be modified
387 by the user.
388
389 * *Remote_Call_Interface*: The unit contains a pragma Remote_Call_Interface.
390
391
392 .. _Example_of_gnatls_Usage:
393
394 Example of ``gnatls`` Usage
395 ---------------------------
396
397 Example of using the verbose switch. Note how the source and
398 object paths are affected by the -I switch.
399
400 ::
401
402 $ gnatls -v -I.. demo1.o
403
404 GNATLS 5.03w (20041123-34)
405 Copyright 1997-2004 Free Software Foundation, Inc.
406
407 Source Search Path:
408 <Current_Directory>
409 ../
410 /home/comar/local/adainclude/
411
412 Object Search Path:
413 <Current_Directory>
414 ../
415 /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
416
417 Project Search Path:
418 <Current_Directory>
419 /home/comar/local/lib/gnat/
420
421 ./demo1.o
422 Unit =>
423 Name => demo1
424 Kind => subprogram body
425 Flags => No_Elab_Code
426 Source => demo1.adb modified
427
428 The following is an example of use of the dependency list.
429 Note the use of the -s switch
430 which gives a straight list of source files. This can be useful for
431 building specialized scripts.
432
433 ::
434
435 $ gnatls -d demo2.o
436 ./demo2.o demo2 OK demo2.adb
437 OK gen_list.ads
438 OK gen_list.adb
439 OK instr.ads
440 OK instr-child.ads
441
442 $ gnatls -d -s -a demo1.o
443 demo1.adb
444 /home/comar/local/adainclude/ada.ads
445 /home/comar/local/adainclude/a-finali.ads
446 /home/comar/local/adainclude/a-filico.ads
447 /home/comar/local/adainclude/a-stream.ads
448 /home/comar/local/adainclude/a-tags.ads
449 gen_list.ads
450 gen_list.adb
451 /home/comar/local/adainclude/gnat.ads
452 /home/comar/local/adainclude/g-io.ads
453 instr.ads
454 /home/comar/local/adainclude/system.ads
455 /home/comar/local/adainclude/s-exctab.ads
456 /home/comar/local/adainclude/s-finimp.ads
457 /home/comar/local/adainclude/s-finroo.ads
458 /home/comar/local/adainclude/s-secsta.ads
459 /home/comar/local/adainclude/s-stalib.ads
460 /home/comar/local/adainclude/s-stoele.ads
461 /home/comar/local/adainclude/s-stratt.ads
462 /home/comar/local/adainclude/s-tasoli.ads
463 /home/comar/local/adainclude/s-unstyp.ads
464 /home/comar/local/adainclude/unchconv.ads
465
466
467 .. only:: PRO or GPL
468
469 .. _The_GNAT_Pretty_Printer_gnatpp:
470
471 The GNAT Pretty Printer ``gnatpp``
472 ==================================
473
474 .. index:: ! gnatpp
475 .. index:: pretty printer
476
477 The ``gnatpp`` tool is a utility for source reformatting / pretty
478 printing. It takes an Ada source file as input and generates a
479 reformatted version as output. You can specify various style
480 directives via switches; e.g., identifier case conventions, rules of
481 indentation, and comment layout.
482
483 ``gnatpp`` 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 ``gnatpp`` switches is named ``Pretty_Printer``.
487
488 ``gnatpp`` cannot process sources that contain preprocessing
489 directives.
490
491 The ``gnatpp`` command has the form
492
493 ::
494
495 $ gnatpp [ switches ] filename
496
497 where
498
499 * ``switches`` is an optional sequence of switches defining such properties
500 as the formatting rules, the source search path, and the destination for
501 the output source file
502
503 * ``filename`` is the name of the source file to reformat; wildcards
504 or several file names on the same gnatpp command are allowed. The
505 file name may contain path information; it does not have to follow
506 the GNAT file naming rules
507
508 Note that it is no longer necessary to specify the Ada language version;
509 ``gnatpp`` can process Ada source code written in any version from Ada 83
510 onward without specifying any language version switch.
511
512
513 .. _Switches_for_gnatpp:
514
515 Switches for ``gnatpp``
516 -----------------------
517
518 The following subsections describe the various switches accepted by
519 ``gnatpp``, organized by category.
520
521 You specify a switch by supplying a name and generally also a value.
522 In many cases the values for a switch with a given name are incompatible
523 with each other
524 (for example the switch that controls the casing of a reserved word may have
525 exactly one value: upper case, lower case, or
526 mixed case) and thus exactly one such switch can be in effect for an
527 invocation of ``gnatpp``.
528 If more than one is supplied, the last one is used.
529 However, some values for the same switch are mutually compatible.
530 You may supply several such switches to ``gnatpp``, but then
531 each must be specified in full, with both the name and the value.
532 Abbreviated forms (the name appearing once, followed by each value) are
533 not permitted.
534
535
536 .. _Layout_Control:
537
538 Layout Control
539 ^^^^^^^^^^^^^^
540
541 .. index:: Layout control in gnatpp
542
543 ``gnatpp`` provides a layout switch which controls the general
544 formatting style:
545
546 .. index:: layout(gnatpp)
547
548 :switch:`--layout=default|minimal|compact|tall`
549
550 :switch:`default`
551 The default layout will follow a compact style but add aligment and put
552 some keywords on a separate line.
553
554 Alignment is added in the the following constructs:
555
556 * ``:`` in declarations,
557 * ``:=`` in initializations in declarations,
558 * ``:=`` in assignment statements,
559 * ``=>`` in associations, and
560 * ``at`` keywords in the component clauses in record representation
561 clauses.
562
563 In addition, ``in`` and ``out`` keywords in parameter specifications are
564 also lined up.
565
566 The keyword ``is`` is placed on a separate line in a subprogram body in
567 case the spec occupies more than one line.
568
569 The keyword ``return`` is placed on a separate line if a subprogram spec
570 does not fit on one line.
571
572 :switch:`minimal`
573 The minimal layout will avoid changing the source layout by keeping all
574 line breaks from the original source (it will not insert or delete any).
575 It will add indentation where appropriate as long as it does not exceed
576 the line length limit.
577
578 :switch:`compact`
579 The compact layout will avoid adding line breaks and alignment by packing
580 as many subexpressions on the same line as possible.
581
582 Whole-line comments that form a paragraph will be filled in typical word
583 processor style (that is, moving words between lines to make them similar
584 in length, except the last one which may be shorter).
585
586 For each whole-line comment that does not end with two hyphens, inserts
587 spaces if necessary after the starting two hyphens to ensure that there
588 are at least two spaces preceding the first non-blank character of the
589 comment.
590
591 :switch:`tall`
592 The tall layout will favor adding lines breaks and alignment. It adds
593 all the alignment and line breaks defined in the ``default`` option,
594 and in addition:
595
596 * Places the keyword ``loop`` in FOR and WHILE loop statements on a
597 separate line
598 * Places the keyword ``then`` in IF statements on a separate line
599 * Places each keyword ``use`` in USE clauses on a separate line
600 * Splits the line just before the keyword ``record`` in a RECORD type
601 declaration
602 * Indents named blocks and loop statments with respect to the name
603 * When necessary, splits binary operators always before the operator
604 * Inserts an extra blank before various occurrences of ``(`` and ``:``
605 * When it is necessary to split a line between two subexpressions (because
606 otherwise the construct would exceed --max-line-length), then all such
607 subexpressions are placed on separate lines
608 * Formats enumeration type declarations “vertically”, e.g. each
609 enumeration literal goes on a separate line
610 * Formats array type declarations “vertically”, e.g. for multidimensional
611 arrays, each index_subtype_definition or discrete_subtype_definition
612 goes on a separate line
613 * Format aggregates “vertically” if named notation is used for all
614 component_associations, e.g. each component_association goes on a
615 separate line
616 * Formats case statements, case expressions, and variant parts with
617 additional line breaks
618 * Inserts blank lines where appropriate (between bodies and other large
619 constructs)
620 * Similarly to the :switch:`compact` layout, two spaces are added in the
621 beginning of a whole-line comment when needed
622
623
624 .. _Casing_Control:
625
626 Casing Control
627 ^^^^^^^^^^^^^^
628
629 .. index:: Casing control in gnatpp
630
631 ``gnatpp`` allows you to specify the casing for reserved words, pragma
632 names, attribute designators and identifiers. For identifiers you may define
633 a general rule for name casing but also override this rule via a set of
634 dictionary files.
635
636 Three types of casing are supported: 'Lower Case', 'Upper Case', and
637 'Mixed Case'. 'Mixed case' means that the first letter, and also each
638 letter immediately following an underscore, are converted to their
639 uppercase forms and all the other letters are converted to their lowercase
640 forms.
641
642 .. index:: --name-case-as-declared (gnatpp)
643
644 :switch:`--name-case-as-declared, -nD`
645 Name casing for defining occurrences are as they appear in the source file
646 (this is the default).
647
648 .. index:: --name-upper-case (gnatpp)
649
650 :switch:`--name-upper-case, -nU`
651 Names are in upper case.
652
653 .. index:: --name-lower-case (gnatpp)
654
655 :switch:`--name-lower-case, -nL`
656 Names are in lower case.
657
658 .. index:: --name-mixed-case (gnatpp)
659
660 :switch:`--name-mixed-case, -nM`
661 Names are in mixed case.
662
663 .. index:: --attribute-lower-case (gnatpp)
664
665 :switch:`--attribute-lower-case, -aL`
666 Attribute designators are lower case.
667
668 .. index:: --attribute-upper-case (gnatpp)
669
670 :switch:`--attribute-upper-case, -aU`
671 Attribute designators are upper case.
672
673 .. index:: --attribute-mixed-case (gnatpp)
674
675 :switch:`--attribute-mixed-case, -aM`
676 Attribute designators are mixed case (this is the default).
677
678 .. index:: --keyword-lower-case (gnatpp)
679
680 :switch:`--keyword-lower-case, -kL`
681 Keywords (technically, these are known in Ada as *reserved words*) are
682 lower case (this is the default).
683
684 .. index:: --keyword-upper-case (gnatpp)
685
686 :switch:`--keyword-upper-case, -kU`
687 Keywords are upper case.
688
689 .. index:: --enum-case-as-declared (gnatpp)
690
691 :switch:`--enum-case-as-declared, -neD`
692 Enumeration literal casing for defining occurrences are as they appear in
693 the source file. Overrides -n casing setting.
694
695 .. index:: --enum-upper-case (gnatpp)
696
697 :switch:`--enum-upper-case, -neU`
698 Enumeration literals are in upper case. Overrides -n casing
699 setting.
700
701 .. index:: --enum-lower-case (gnatpp)
702
703 :switch:`--enum-lower-case, -neL`
704 Enumeration literals are in lower case. Overrides -n casing
705 setting.
706
707 .. index:: --enum-mixed-case (gnatpp)
708
709 :switch:`--enum-mixed-case, -neM`
710 Enumeration literals are in mixed case. Overrides -n casing
711 setting.
712
713 .. index:: --type-case-as-declared (gnatpp)
714
715 :switch:`--type-case-as-declared, -ntD`
716 Names introduced by type and subtype declarations are always
717 cased as they appear in the declaration in the source file.
718 Overrides -n casing setting.
719
720 .. index:: --type-upper-case (gnatpp)
721
722 :switch:`--type-upper-case, -ntU`
723 Names introduced by type and subtype declarations are always in
724 upper case. Overrides -n casing setting.
725
726 .. index:: --type-lower-case (gnatpp)
727
728 :switch:`--type-lower-case, -ntL`
729 Names introduced by type and subtype declarations are always in
730 lower case. Overrides -n casing setting.
731
732 .. index:: --type-mixed-case (gnatpp)
733
734 :switch:`--type-mixed-case, -ntM`
735 Names introduced by type and subtype declarations are always in
736 mixed case. Overrides -n casing setting.
737
738 .. index:: --number-upper-case (gnatpp)
739
740 :switch:`--number-upper-case, -nnU`
741 Names introduced by number declarations are always in
742 upper case. Overrides -n casing setting.
743
744 .. index:: --number-lower-case (gnatpp)
745
746 :switch:`--number-lower-case, -nnL`
747 Names introduced by number declarations are always in
748 lower case. Overrides -n casing setting.
749
750 .. index:: --number-mixed-case (gnatpp)
751
752 :switch:`--number-mixed-case, -nnM`
753 Names introduced by number declarations are always in
754 mixed case. Overrides -n casing setting.
755
756 .. index:: --pragma-lower-case (gnatpp)
757
758 :switch:`--pragma-lower-case, -pL`
759 Pragma names are lower case.
760
761 .. index:: --pragma-upper-case (gnatpp)
762
763 :switch:`--pragma-upper-case, -pU`
764 Pragma names are upper case.
765
766 .. index:: --pragma-mixed-case (gnatpp)
767
768 :switch:`--pragma-mixed-case, -pM`
769 Pragma names are mixed case (this is the default).
770
771 .. index:: --constant-case-as-non-constant (gnatpp)
772
773 :switch:`--constant-case-as-non-constant, -cN`
774 Constant object declaration names have the same case as the name casing
775 (this is the default).
776
777 .. index:: --constant-case-as-declared (gnatpp)
778
779 :switch:`--constant-case-as-declared, -cD`
780 Constant object declaration names are as they appear in the source file.
781
782 .. index:: --constant-lower-case (gnatpp)
783
784 :switch:`--constant-lower-case, -cL`
785 Constant object declaration names are lower case.
786
787 .. index:: --constant-upper-case (gnatpp)
788
789 :switch:`--constan-upper-case, -cU`
790 Constant object declaration names are upper case.
791
792 .. index:: --constant-mixed-case (gnatpp)
793
794 :switch:`--constant-mixed-case, -cM`
795 Constant object declaration names are mixed case.
796
797 .. index:: --syntax-only (gnatpp)
798
799 :switch:`--syntax-only`
800 Disable the semantic analysis (name resolution) done by libadalang.
801 This means gnatpp will not be able to support any of the
802 "as-declared" switches.
803
804 .. index:: --dictionary (gnatpp)
805
806 :switch:`--dictionary={file}, -D={file}`
807 Use ``file`` as a *dictionary file* that defines
808 the casing for a set of specified names,
809 thereby overriding the effect on these names by
810 any explicit or implicit
811 -n switch.
812 To supply more than one dictionary file,
813 use several ``--dictionary`` switches.
814
815 ``gnatpp`` implicitly uses a *default dictionary file*
816 to define the casing for the Ada predefined names and
817 the names declared in the GNAT libraries.
818
819 .. index:: --dictionary=- (gnatpp)
820
821 :switch:`--dictionary=-, -D=-`
822 Do not use the default dictionary file;
823 instead, use the casing
824 defined by a ``-n`` switch and any explicit
825 dictionary file(s)
826
827 The structure of a dictionary file, and details on the conventions
828 used in the default dictionary file, are defined in :ref:`Name_Casing`.
829
830 The :switch:`--dictionary=-` and
831 :switch:`--dictionary={file}` switches are mutually
832 compatible.
833
834 This group of ``gnatpp`` switches controls the layout of comments and
835 complex syntactic constructs. See :ref:`Formatting_Comments` for details
836 on their effect.
837
838
839 .. _General_Text_Layout_Control:
840
841 General Text Layout Control
842 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
843
844 These switches allow control over line length and indentation.
845
846 .. index:: --max-line-length (gnatpp)
847
848 :switch:`--max-line-length={nnn}, -M={nnn}`
849 Maximum line length, ``nnn`` from 32...256, the default value is 79
850
851
852 .. index:: --indentation (gnatpp)
853
854 :switch:`--indentation={nnn}, -i={nnn}`
855 Indentation level, ``nnn`` from 1...9, the default value is 3
856
857
858 .. index:: --indent-continuation (gnatpp)
859
860 :switch:`--indent-continuation={nnn}, -cl={nnn}`
861 Indentation level for continuation lines (relative to the line being
862 continued), ``nnn`` from 1...9.
863 The default
864 value is one less than the (normal) indentation level, unless the
865 indentation is set to 1 (in which case the default value for continuation
866 line indentation is also 1)
867
868
869 .. _Other_Formatting_Options:
870
871 Other Formatting Options
872 ^^^^^^^^^^^^^^^^^^^^^^^^
873
874 These switches control other formatting not listed above.
875
876 .. index:: --decimal-grouping (gnatpp)
877
878 :switch:`--decimal-grouping={n}`
879 Put underscores in decimal literals (numeric literals without a base)
880 every ``n`` characters. If a literal already has one or more
881 underscores, it is not modified. For example, with
882 ``--decimal-grouping=3``, ``1000000`` will be changed to
883 ``1_000_000``.
884
885
886 .. index:: --based-grouping (gnatpp)
887
888 :switch:`--based-grouping={n}`
889 Same as ``--decimal-grouping``, but for based literals. For
890 example, with ``--based-grouping=4``, ``16#0001FFFE#`` will be
891 changed to ``16#0001_FFFE#``.
892
893 .. index:: --call-threshold (gnatpp)
894
895 :switch:`--call-threshold={nnn}`
896 If the number of parameter associations is greater than ``nnn`` and if at
897 least one association uses named notation, start each association from
898 a new line. If ``nnn`` is 0, no check for the number of associations
899 is made; this is the default.
900
901 .. index:: --par-threshold (gnatpp)
902
903 :switch:`--par-threshold={nnn}`
904 If the number of parameter specifications is greater than ``nnn``
905 (or equal to ``nnn`` in case of a function), start each specification from
906 a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not
907 specified, then the ``is`` is placed on a separate line. This feature is
908 disabled by default.
909
910
911 .. _Setting_the_Source_Search_Path:
912
913 Setting the Source Search Path
914 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
915
916 To define the search path for the input source file, ``gnatpp``
917 uses the same switches as the GNAT compiler, with the same effects:
918
919 .. index:: -I (gnatpp)
920
921
922 :switch:`-I{dir}`
923
924 .. index:: -I- (gnatpp)
925
926 :switch:`-I-`
927
928 .. index:: -gnatec (gnatpp)
929
930 :switch:`-gnatec={path}`
931
932
933 .. _Output_File_Control-gnatpp:
934
935 Output File Control
936 ^^^^^^^^^^^^^^^^^^^
937
938 By default the output overwrites the input file.
939 The output may be redirected by the following switches:
940
941
942 .. index:: --replace (gnatpp)
943
944 :switch:`--replace, -rnb`
945 This is the default.
946 Replace the input source file with the reformatted output without
947 creating any backup copy of the input source.
948
949
950 .. index:: --output-dir (gnatpp)
951
952 :switch:`--output-dir={dir}`
953 Generate output file in directory :file:`dir` with the same name as
954 the input file. If :file:`dir` is the same as the directory
955 containing the input file, the input file is not processed; use
956 ``--replace`` if you want to update the input file in
957 place.
958
959
960 .. index:: --pipe (gnatpp)
961
962 :switch:`--pipe, -pipe`
963 Send the output to ``Standard_Output``
964
965
966 .. index:: --output (gnatpp)
967
968 :switch:`--output={output_file}, -o={output_file}`
969 Write the output into ``output_file``.
970 If ``output_file`` already exists, ``gnatpp`` terminates without
971 reading or processing the input file.
972
973
974 .. index:: --output-force (gnatpp)
975
976 :switch:`--output-force={output_file}, -of={output_file}`
977 Write the output into ``output_file``, overwriting the existing file
978 (if one is present).
979
980
981 .. index:: --replace-backup (gnatpp)
982
983 :switch:`--replace-backup, -r`
984 Replace the input source file with the reformatted output, and copy the
985 original input source into the file whose name is obtained by appending
986 the :file:`.npp` suffix to the name of the input file.
987 If a file with this name already exists, ``gnatpp`` terminates without
988 reading or processing the input file.
989
990
991 .. index:: --replace-force-backup (gnatpp)
992
993 :switch:`--replace-force-backup, -rf`
994 Like ``--replace-backup`` except that if the file with the specified name
995 already exists, it is overwritten.
996
997
998 .. index:: --eol (gnatpp)
999
1000 :switch:`--eol={xxx}`
1001 Specifies the line-ending style of the reformatted output file. The
1002 ``xxx`` string specified with the switch may be:
1003
1004 * *dos* - MS DOS style, lines end with CR LF characters*
1005 * *crlf* - the same as *dos*
1006 * *unix* - UNIX style, lines end with LF character*
1007 * *lf* - the same as *unix*
1008
1009 The default is to use the same end-of-line convention as the input.
1010
1011 .. index:: --wide-character-encoding (gnatpp)
1012
1013 :switch:`--wide-character-encoding={e}, -W={e}`
1014 Specify the wide character encoding method for the input and output
1015 files. ``e`` is one of the following:
1016
1017 * *8* - UTF-8 encoding
1018
1019 * *b* - Brackets encoding (default value)
1020
1021 Options ``--output-file`` and ``--output-force`` are allowed only if
1022 the call to gnatpp contains only one file to reformat.
1023
1024 Option ``--eol`` and ``--wide-character-encoding`` cannot be used together
1025 with the ``--pipe`` option.
1026
1027
1028 .. _Other_gnatpp_Switches:
1029
1030 Other ``gnatpp`` Switches
1031 ^^^^^^^^^^^^^^^^^^^^^^^^^
1032
1033 The additional ``gnatpp`` switches are defined in this subsection.
1034
1035
1036 .. index:: --version (gnatpp)
1037
1038 :switch:`--version`
1039 Display copyright and version, then exit disregarding all other options.
1040
1041
1042 .. index:: --help (gnatpp)
1043
1044 :switch:`--help`
1045 Display usage, then exit disregarding all other options.
1046
1047
1048 .. index:: -P (gnatpp)
1049
1050 :switch:`-P {file}`
1051 Indicates the name of the project file that describes the set of sources
1052 to be processed. The exact set of argument sources depends on other
1053 options specified; see below.
1054
1055
1056 .. index:: -U (gnatpp)
1057
1058 :switch:`-U`
1059 If a project file is specified and no argument source is explicitly
1060 specified (either directly or by means of ``--files`` option), process
1061 all the units of the closure of the argument project. Otherwise this
1062 option has no effect.
1063
1064 :switch:`-U {main_unit}`
1065 If a project file is specified and no argument source is explicitly
1066 specified (either directly or by means of ``--files`` option), process
1067 the closure of units rooted at ``main_unit``. Otherwise this option
1068 has no effect.
1069
1070
1071 .. index:: -X (gnatpp)
1072
1073 :switch:`-X{name}={value}`
1074 Indicates that external variable ``name`` in the argument project
1075 has the value ``value``. Has no effect if no project is specified.
1076
1077
1078 .. index:: --RTS (gnatpp)
1079
1080 :switch:`--RTS={rts-path}`
1081 Specifies the default location of the runtime library. Same meaning as the
1082 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
1083
1084
1085 .. index:: --incremental (gnatpp)
1086
1087 :switch:`--incremental`
1088 Incremental processing on a per-file basis. Source files are only
1089 processed if they have been modified, or if files they depend on have
1090 been modified. This is similar to the way gnatmake/gprbuild only
1091 compiles files that need to be recompiled. A project file is required
1092 in this mode, and the gnat driver (as in *gnat pretty*) is not
1093 supported.
1094 (Note: this switch is not yet supported in the libadalang-based
1095 version of gnatpp.)
1096
1097
1098 .. index:: --pp-off (gnatpp)
1099
1100 :switch:`--pp-off={xxx}`
1101 Use :switch:`--xxx` as the command to turn off pretty printing, instead
1102 of the default ``--!pp off``.
1103
1104
1105 .. index:: --pp-on (gnatpp)
1106
1107 :switch:`--pp-on={xxx}`
1108 Use :switch:`--xxx` as the command to turn pretty printing back on,
1109 instead of the default ``--!pp on``.
1110
1111
1112 .. index:: --files (gnatpp)
1113
1114 :switch:`--files={filename}, -files={filename}`
1115 Take as arguments the files listed in text file ``file``.
1116 Text file ``file`` may contain empty lines that are ignored.
1117 Each nonempty line should contain the name of an existing file.
1118 Several such switches may be specified simultaneously.
1119
1120
1121 .. index:: --ignore (gnatpp)
1122
1123 :switch:`--ignore={filename}`
1124 Do not process the sources listed in a specified file. This option cannot
1125 be used in incremental mode.
1126
1127
1128 .. index:: --jobs (gnatpp)
1129
1130 :switch:`--jobs={n}, -j={n}`
1131 With ``--incremental``, use *n* ``gnatpp`` processes to perform
1132 pretty printing in parallel. If *n* is 0, then the maximum number
1133 processes is the number of core processors on the platform.
1134
1135
1136 .. index:: --verbose (gnatpp)
1137
1138 :switch:`--verbose, -v`
1139 Verbose mode
1140
1141
1142 .. index:: --quiet (gnatpp)
1143
1144 :switch:`--quiet, -q`
1145 Quiet mode
1146
1147 If a project file is specified and no argument source is explicitly
1148 specified (either directly or by means of ``--files`` option), and no
1149 ``-U`` is specified, then the set of processed sources is
1150 all the immediate units of the argument project.
1151
1152
1153 .. _Formatting_Rules:
1154
1155 Formatting Rules
1156 ----------------
1157
1158 The following subsections show how ``gnatpp`` treats, comments, program
1159 layout, name casing and how to disable ``gnatpp`` in source code regions.
1160 They provide more details of the switches shown above.
1161
1162
1163 .. _Disabling_Pretty_Printing:
1164
1165 Disabling Pretty Printing
1166 ^^^^^^^^^^^^^^^^^^^^^^^^^
1167
1168 Pretty printing is highly heuristic in nature, and sometimes doesn't
1169 do exactly what you want. If you wish to format a certain region of
1170 code by hand, you can turn off pretty printing in that region by
1171 surrounding it with special comments that start with ``--!pp off``
1172 and ``--!pp on``. The text in that region will then be reproduced
1173 verbatim in the output with no formatting.
1174
1175 To disable pretty printing for the whole file, put ``--!pp off`` at
1176 the top, with no following ``--!pp on``.
1177
1178 The comments must appear on a line by themselves, with nothing
1179 preceding except spaces. The initial text of the comment must be
1180 exactly ``--!pp off`` or ``--!pp on`` (case sensitive), but may
1181 be followed by arbitrary additional text. For example:
1182
1183 .. code-block:: ada
1184
1185 package Interrupts is
1186 --!pp off -- turn off pretty printing so "Interrupt_Kind" lines up
1187 type Interrupt_Kind is
1188 (Asynchronous_Interrupt_Kind,
1189 Synchronous_Interrupt_Kind,
1190 Green_Interrupt_Kind);
1191 --!pp on -- reenable pretty printing
1192 ...
1193
1194 You can specify different comment strings using the ``--pp-off``
1195 and ``--pp-on`` switches. For example, if you say:
1196
1197 ::
1198
1199 $ gnatpp --pp-off=' pp-' *.ad?
1200
1201 then gnatpp will recognize comments of the form
1202 ``-- pp-`` instead of ``--!pp off`` for disabling pretty
1203 printing. Note that the leading ``--`` of the comment is not
1204 included in the argument to these switches.
1205
1206
1207 .. _Formatting_Comments:
1208
1209 Formatting Comments
1210 ^^^^^^^^^^^^^^^^^^^
1211
1212 Only ``--layout=compact`` and ``--layout=tall`` format comments.
1213
1214 Comments in Ada code are of two kinds:
1215
1216 * a *whole-line comment*, which appears by itself (possibly preceded by
1217 white space) on a line
1218
1219 * an *end-of-line comment*, which follows some other Ada code on
1220 the same line.
1221
1222 A whole-line comment is indented according to the surrounding code,
1223 with some exceptions. Comments that start in column 1 are kept
1224 there. If possible, comments are not moved so far to the right that
1225 the maximum line length is exceeded. Special-form comments such as
1226 SPARK-style ``--#...`` are left alone.
1227
1228 For an end-of-line comment, ``gnatpp`` tries to leave the same
1229 number of spaces between the end of the preceding Ada code and the
1230 beginning of the comment as appear in the original source.
1231
1232 For each whole-line comment that does not end with two hyphens or that are
1233 not special-form comments, ``gnatpp`` inserts spaces if necessary after the
1234 starting two hyphens to ensure that there are at least two spaces between
1235 these hyphens and the first non-blank character of the comment.
1236
1237 With ``--layout=compact``, whole-line comments that form a paragraph will be
1238 filled in typical word processor style (that is, moving words between lines
1239 to make the lines other than the last similar in length).
1240
1241
1242 .. _Name_Casing:
1243
1244 Name Casing
1245 ^^^^^^^^^^^
1246
1247 ``gnatpp`` always converts the usage occurrence of a (simple) name to
1248 the same casing as the corresponding defining identifier.
1249
1250 You control the casing for defining occurrences via the ``--name...``
1251 switches. With ``--name-case-as-declared``, which is the default,
1252 defining occurrences appear exactly as in the source file where they
1253 are declared. The other values for this switch --
1254 ``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
1255 -- result in upper, lower, or mixed case, respectively. If
1256 ``gnatpp`` changes the casing of a defining occurrence, it
1257 analogously changes the casing of all the usage occurrences of this
1258 name.
1259
1260 If the defining occurrence of a name is not in the source compilation
1261 unit currently being processed by ``gnatpp``, the casing of each
1262 reference to this name is changed according to the switch (subject to
1263 the dictionary file mechanism described below). Thus ``gnatpp`` acts
1264 as though the switch had affected the casing for the defining
1265 occurrence of the name.
1266
1267 The options
1268 :switch:`--attribute...`,
1269 :switch:`--keyword...`,
1270 :switch:`--enum...`,
1271 :switch:`--type...`,
1272 :switch:`--number...`, and
1273 :switch:`--pragma...`
1274 allow finer-grained control over casing for
1275 attributes, keywords, enumeration literals,
1276 types, named numbers and pragmas, respectively.
1277 :switch:`--type...` cover subtypes as well.
1278
1279 Some names may need to be spelled with casing conventions that are not
1280 covered by the upper-, lower-, and mixed-case transformations.
1281 You can arrange correct casing by placing such names in a
1282 *dictionary file*,
1283 and then supplying a ``--dictionary`` switch.
1284 The casing of names from dictionary files overrides
1285 any ``--name...`` switch.
1286
1287 To handle the casing of Ada predefined names and the names from GNAT libraries,
1288 ``gnatpp`` assumes a default dictionary file.
1289 The name of each predefined entity is spelled with the same casing as is used
1290 for the entity in the :title:`Ada Reference Manual` (usually mixed case).
1291 The name of each entity in the GNAT libraries is spelled with the same casing
1292 as is used in the declaration of that entity.
1293
1294 The ``--dictionary=-`` switch suppresses the use of
1295 the default dictionary file. Instead, the casing for predefined and
1296 GNAT-defined names will be established by the
1297 ``-n`` switch or explicit dictionary files. For
1298 example, by default the names ``Ada.Text_IO`` and
1299 ``GNAT.OS_Lib`` will appear as just shown, even in the presence of
1300 a ``--name-upper-case`` switch. To ensure that even
1301 such names are rendered in uppercase, additionally supply the
1302 --dictionary=- switch (or else place these names
1303 in upper case in a dictionary file).
1304
1305 A dictionary file is a plain text file; each line in this file can be
1306 either a blank line (containing only space characters), an Ada comment
1307 line, or the specification of exactly one *casing schema*.
1308
1309 A casing schema is a string that has the following syntax:
1310
1311 ::
1312
1313 casing_schema ::= identifier | simple_identifier
1314
1315 simple_identifier ::= letter{letter_or_digit}
1316
1317
1318 (See :title:`Ada Reference Manual`, Section 2.3) for the definition of the
1319 ``identifier`` lexical element and the ``letter_or_digit`` category.)
1320
1321 The casing schema string can be followed by white space and/or an Ada-style
1322 comment; any amount of white space is allowed before the string.
1323
1324 If a dictionary file is passed as
1325 the value of a :switch:`--dictionary={file}` switch
1326 then for every
1327 simple name and every identifier, ``gnatpp`` checks if the dictionary
1328 defines the casing for the name or for some of its parts (the term 'subword'
1329 is used below to denote the part of a name which is delimited by '_' or by
1330 the beginning or end of the word and which does not contain any '_' inside):
1331
1332 * if the whole name is in the dictionary, ``gnatpp`` uses for this name
1333 the casing defined by the dictionary; no subwords are checked for this word
1334
1335 * for every subword ``gnatpp`` checks if the dictionary contains the
1336 corresponding string of the form ``simple_identifier``,
1337 and if it does, the casing of this ``simple_identifier`` is used
1338 for this subword
1339
1340 * if the whole name does not contain any '_' inside, and if for this name
1341 the dictionary contains two entries -- one of the form ``identifier``,
1342 and another of the form ``simple_identifier`` -- then the first one
1343 is applied to define the casing of this name
1344
1345 * if more than one dictionary file is passed as ``gnatpp`` switches, each
1346 dictionary adds new casing exceptions and overrides all the existing casing
1347 exceptions set by the previous dictionaries
1348
1349 * when ``gnatpp`` checks if the word or subword is in the dictionary,
1350 this check is not case sensitive
1351
1352 For example, suppose we have the following source to reformat:
1353
1354 .. code-block:: ada
1355
1356 procedure test is
1357 name1 : integer := 1;
1358 name4_name3_name2 : integer := 2;
1359 name2_name3_name4 : Boolean;
1360 name1_var : Float;
1361 begin
1362 name2_name3_name4 := name4_name3_name2 > name1;
1363 end;
1364
1365 And suppose we have two dictionaries:
1366
1367 ::
1368
1369 *dict1:*
1370 NAME1
1371 *NaMe3*
1372 *Name1*
1373
1374 *dict2:*
1375 *NAME3*
1376
1377 If ``gnatpp`` is called with the following switches:
1378
1379 ::
1380
1381 $ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb
1382
1383 then we will get the following name casing in the ``gnatpp`` output:
1384
1385
1386 .. code-block:: ada
1387
1388 procedure Test is
1389 NAME1 : Integer := 1;
1390 Name4_NAME3_Name2 : Integer := 2;
1391 Name2_NAME3_Name4 : Boolean;
1392 Name1_Var : Float;
1393 begin
1394 Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
1395 end Test;
1396
1397 .. _Preprocessor_directives:
1398
1399 Preprocessor Directives
1400 ^^^^^^^^^^^^^^^^^^^^^^^
1401
1402 ``gnatpp`` has some support for preprocessor directives.
1403 You can use preprocessor symbols, as in ``$symbol``.
1404 In addition, you can use conditional compilation,
1405 so long as the program text is syntactically legal Ada code
1406 after removing all the preprocessor directives (lines starting
1407 with ``#``). For example, ``gnatpp`` can format the following:
1408
1409 .. code-block:: ada
1410
1411 package P is
1412 #IF SOMETHING
1413 X : constant Integer := 123;
1414 #ELSE
1415 X : constant Integer := 456;
1416 #END IF;
1417 end P;
1418
1419 which will be formatted as if it were:
1420
1421 .. code-block:: ada
1422
1423 package P is
1424 X : constant Integer := 123;
1425 X : constant Integer := 456;
1426 end P;
1427
1428 except that the ``#`` lines will be preserved.
1429 However, ``gnatpp`` cannot format the following:
1430
1431 .. code-block:: ada
1432
1433 procedure P is
1434 begin
1435 #IF SOMETHING
1436 if X = 0 then
1437 #ELSE
1438 if X = 1 then
1439 #END IF;
1440 null;
1441 end if;
1442 end P;
1443
1444 because removing the ``#`` lines gives:
1445
1446 .. code-block:: ada
1447
1448 procedure P is
1449 begin
1450 if X = 0 then
1451 if X = 1 then
1452 null;
1453 end if;
1454 end P;
1455
1456 which is not syntactically legal.
1457
1458 Legacy Switches
1459 ^^^^^^^^^^^^^^^
1460
1461 .. index:: --alignment (gnatpp)
1462
1463 :switch:`--alignment, --no-alignment`
1464 Programs can be easier to read if certain constructs are vertically
1465 aligned.
1466
1467 * ``:`` in declarations,
1468 * ``:=`` in initializations in declarations,
1469 * ``:=`` in assignment statements,
1470 * ``=>`` in associations, and
1471 * ``at`` keywords in the component clauses in record representation
1472 clauses.
1473
1474 .. index:: --align-modes (gnatpp)
1475
1476 :switch:`--align-modes, --no-align-modes`
1477
1478 Line up ``in`` and ``out`` in parameter specifications.
1479
1480 .. index:: --compact (gnatpp)
1481
1482 :switch:`--compact, --no-compact`
1483 In calls and similar, ``--compact`` packs as many
1484 subexpressions on the same line as possible. Example:
1485
1486 .. code-block:: ada
1487
1488 Some_Procedure
1489 (Short_One, Another_Short_One,
1490 A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
1491
1492 On the contrary, with ``--no-compact``, in calls and similar, if it is
1493 necessary to split a line between two subexpressions (because otherwise
1494 the construct would exceed --max-line-length), then all such
1495 subexpressions are placed on separate lines. Example:
1496
1497 .. code-block:: ada
1498
1499 Some_Procedure
1500 (Short_One,
1501 Another_Short_One,
1502 A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
1503
1504 .. index:: --end-id (gnatpp)
1505
1506 :switch:`--end-id, --no-end-id`
1507 Insert the name of a unit after ``end``. Otherwise, leave whatever comes
1508 after ``end``, if anything, alone.
1509
1510 .. index:: --separate-is (gnatpp)
1511
1512 :switch:`--separate-is, --no-separate-is`
1513 Place the keyword ``is`` on a separate line in a subprogram body in
1514 case if the spec occupies more than one line.
1515
1516 .. index:: --separate-return (gnatpp)
1517
1518 :switch:`--separate-return, --no-separate-return`
1519 If a subprogram spec does not fit on one line, place the ``return`` on
1520 a separate line. Otherwise try to place it in the same line as the last
1521 parameter specification.
1522
1523 .. index:: --separate-loop (gnatpp)
1524
1525 :switch:`--separate-loop, --no-separate-loop`
1526 Place the keyword ``loop`` in FOR and WHILE loop statements
1527 on a separate line.
1528
1529
1530 .. index:: --separate-then (gnatpp)
1531
1532 :switch:`--separate-then, --no-separate-then`
1533 Place the keyword ``then`` in IF statements
1534 on a separate line.
1535
1536 .. index:: --separate-loop-then (gnatpp)
1537
1538 :switch:`--separate-loop-then, --no-separate-loop-then`
1539 Equivalent to :switch:`--separate-loop` :switch:`--separate-then`.
1540
1541 .. index:: --split-line-before-record (gnatpp)
1542
1543 :switch:`--split-line-before-record, --no-split-line-before-record`
1544 Split the line just before ``record`` in a record type declaration.
1545
1546 .. index:: --indent-named-statements (gnatpp)
1547
1548 :switch:`--indent-named-statements, --no-indent-named-statements`
1549 Named block and loop statements are indented with respect to
1550 the name.
1551
1552 .. index:: --split-line-before-op (gnatpp)
1553
1554 :switch:`--split-line-before-op, --no-split-line-before-op`
1555 If it is necessary to split a line at a binary operator, by default
1556 the line is split after the operator. With this option, it is split
1557 before the operator.
1558
1559 .. index:: --use-on-new-line (gnatpp)
1560
1561 :switch:`--use-on-new-line, --no-use-one-new-line`
1562 Start each USE clause in a context clause from a separate line.
1563
1564 .. index:: --vertical-enum-types (gnatpp)
1565
1566 :switch:`--vertical-enum-types, --no-vertical-enum-types`
1567 Format enumeration type declarations "vertically", e.g. each
1568 enumeration literal goes on a separate line.
1569
1570 .. index:: --vertical-array-types (gnatpp)
1571
1572 :switch:`--vertical-array-types, --no-vertical-array-types`
1573 Format array type declarations "vertically", e.g. for
1574 multidimensional arrays, each index_subtype_definition or
1575 discrete_subtype_definition goes on a separate line.
1576
1577 .. index:: --vertical-named-aggregates (gnatpp)
1578
1579 :switch:`--vertical-named-aggregates, --no-vertical-named-aggregates`
1580 Format aggregates "vertically" if named notation is used for all
1581 component_associations, e.g. each component_association
1582 goes on a separate line.
1583
1584 .. index:: --vertical-case-alternatives (gnatpp)
1585
1586 :switch:`--vertical-case-alternatives, --no-vertical-case-alternatives`
1587 Format case statements, case expressions, and variant parts with
1588 additional line breaks.
1589
1590 .. index:: --RM-style-spacing (gnatpp)
1591
1592 :switch:`--RM-style-spacing`
1593 Do not insert an extra blank before various occurrences of
1594 '(' and ':'. Alignment is off by default in this mode;
1595 use :switch:`--alignment` to turn it on.
1596
1597 .. index:: --insert-blank-lines (gnatpp)
1598
1599 :switch:`--insert-blank-lines, --no-insert-blank-lines`
1600 Insert blank lines where appropriate (between bodies and other large
1601 constructs).
1602
1603 .. index:: --preserve-blank-lines (gnatpp)
1604
1605 :switch:`--preserve-blank-lines, --no-preserve-blank-lines`
1606 Preserve blank lines in the input. By default, gnatpp will squeeze
1607 multiple blank lines down to one.
1608
1609 .. index:: --preserve-line-breaks (gnatpp)
1610
1611 :switch:`--preserve-line-breaks, --no-preserve-line-breaks`
1612 Preserve line breaks in the input, to the extent possible.
1613 By default, line breaks are also inserted at appropriate
1614 places.
1615
1616 .. index:: --source-line-breaks (gnatpp)
1617
1618 :switch:`--source-line-breaks, --no-source-line-breaks`
1619 Keep the line breaks from the source; do not insert or delete any
1620 line breaks.
1621
1622 .. index:: --spaces-only (gnatpp)
1623
1624 :switch:`--spaces-only, --no-spaces-only`
1625 Disable all formatting except for inserting and removing spaces.
1626 This implies --source-line-breaks.
1627
1628 .. index:: -c (gnatpp)
1629
1630 :switch:`--comments-unchanged, -c0`
1631 All comments remain unchanged.
1632
1633 :switch:`--comments-gnat-indentation, -c1`
1634 GNAT-style comment line indentation.
1635
1636 :switch:`--comments-gnat-beginning, -c3`
1637 GNAT-style comment beginning.
1638
1639 :switch:`--comments-fill, -c4`
1640 Fill comment blocks.
1641
1642 :switch:`--comments-special, -c5`
1643 Keep unchanged special form comments.
1644
1645 :switch:`--comments-only`
1646 Format just the comments.
1647
1648
1649 .. only:: PRO or GPL
1650
1651 .. _The_Body_Stub_Generator_gnatstub:
1652
1653 The Body Stub Generator *gnatstub*
1654 ==================================
1655
1656 .. index:: ! gnatstub
1657
1658 ``gnatstub`` creates empty but compilable bodies
1659 for library unit declarations, and empty but compilable
1660 subunits for body stubs.
1661
1662 ``gnatstub`` is a project-aware tool.
1663 (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
1664 the project-related switches but note that ``gnatstub`` does not support
1665 the :switch:`-U`, :switch:`-U {main_unit}`, :switch:`--subdirs={dir}`, or
1666 :switch:`--no-objects-dir` switches.)
1667 The project file package that can specify
1668 ``gnatstub`` switches is named ``gnatstub``.
1669
1670
1671 By default, all the program unit bodies generated by ``gnatstub``
1672 raise ``Program_Error``, which will catch accidental calls of
1673 generated stubs. This behavior can be changed with option
1674 ``--no-exception`` (see below).
1675
1676 .. _Running_gnatstub:
1677
1678 Running ``gnatstub``
1679 --------------------
1680
1681 ``gnatstub`` invocation has the following form:
1682
1683 ::
1684
1685 $ gnatstub [ switches ] {filename}
1686
1687 where
1688
1689 * *filename*
1690 is the name of the source file that contains a library unit declaration
1691 for which a body must be created or a library unit body for which subunits
1692 must be created for the body stubs declared in this body.
1693 The file name may contain path information.
1694 If the name does not follow GNAT file naming conventions and the set
1695 of switches does not contain a project file that defines naming
1696 conventions, the name of the body file must
1697 be provided
1698 explicitly as the value of the :switch:`--output={body-name}` option.
1699 If the file name follows the GNAT file naming
1700 conventions and the name of the body file is not provided,
1701 ``gnatstub``
1702 takes the naming conventions for the generated source from the
1703 project file provided as a parameter of ``-P`` switch if any,
1704 or creates the name file to generate using the standard GNAT
1705 naming conventions.
1706
1707 Note that it is no longer necessary to specify the Ada language version;
1708 ``gnatstub`` can process Ada source code written in any version from
1709 Ada 83 onward without specifying any language version switch.
1710
1711 * *switches*
1712 is an optional sequence of switches as described in the next section
1713
1714
1715 .. _Switches_for_gnatstub:
1716
1717 Switches for ``gnatstub``
1718 -------------------------
1719
1720 .. index:: --version (gnatstub)
1721
1722 :switch:`--version`
1723 Display copyright and version, then exit disregarding all other options.
1724
1725
1726 .. index:: --help (gnatstub)
1727
1728 :switch:`--help`
1729 Display usage, then exit disregarding all other options.
1730
1731
1732 .. index:: -P (gnatstub)
1733
1734 :switch:`-P {file}`
1735 Indicates the name of the project file that describes the set of sources
1736 to be processed. An aggregate project is allowed as the file parameter only
1737 if it has exactly one non-aggregate project being aggregated.
1738
1739
1740 .. index:: -X (gnatstub)
1741
1742 :switch:`-X{name}={value}`
1743 Indicates that external variable ``name`` in the argument project
1744 has the value ``value``. Has no effect if no project is specified.
1745
1746
1747 .. index:: --RTS (gnatstub)
1748
1749 :switch:`--RTS={rts-path}`
1750 Specifies the default location of the runtime library. Same meaning as the
1751 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
1752
1753
1754 .. index:: --subunits (gnatstub)
1755
1756 :switch:`--subunits`
1757 Generate subunits for body stubs. If this switch is specified,
1758 ``gnatstub`` expects a library unit body as an argument file;
1759 otherwise a library unit declaration is expected. If a body stub
1760 already has a corresponding subunit, ``gnatstub`` does not
1761 generate anything for it.
1762
1763
1764 .. index:: --force (gnatstub)
1765
1766 :switch:`--force`
1767 If the destination directory already contains a file with the name of the
1768 body file
1769 for the argument spec file, replace it with the generated body stub.
1770 This switch cannot be used together with ``--subunits``.
1771
1772
1773 .. index:: --comment-header-spec (gnatstub)
1774
1775 :switch:`--comment-header-spec`
1776 Put the comment header (i.e., all the comments preceding the
1777 compilation unit) from the source of the library unit declaration
1778 into the body stub.
1779
1780
1781 .. index:: --comment-header-sample (gnatstub)
1782
1783 :switch:`--comment-header-sample`
1784 Put a sample comment header into the body stub.
1785
1786
1787 .. index:: --header-file (gnatstub)
1788
1789 :switch:`--header-file={filename}`
1790 Use the content of the file as the comment header for a generated body stub.
1791
1792
1793 .. index:: --max-line-length (gnatstub)
1794
1795 :switch:`--max-line-length={n}`
1796 (``n`` is a non-negative integer). Set the maximum line length for
1797 the output files. The default is 79. The maximum value that can be
1798 specified is 32767.
1799
1800
1801 .. index:: --indentation (gnatstub)
1802
1803 :switch:`--indentation={n}`
1804 (``n`` is an integer from 1 to 9). Set the indentation level in
1805 the generated files to ``n``.
1806 The default indentation is 3.
1807
1808
1809 .. index:: --alphabetical-order (gnatstub)
1810
1811 :switch:`--alphabetical-order`
1812 Order local bodies alphabetically. (By default local bodies are ordered
1813 in the same way as the corresponding local specs in the argument
1814 spec file.)
1815
1816
1817 .. index:: --no-exception (gnatstub)
1818
1819 :switch:`--no-exception`
1820 Avoid raising Program_Error in the generated bodies of program unit stubs,
1821 except in the case of functions, where we have no value to return.
1822
1823
1824 .. index:: --no-local-header (gnatstub)
1825
1826 :switch:`--no-local-header`
1827 Do not place local comment header with unit name before body stub for a
1828 unit.
1829
1830
1831 .. index:: --files (gnatstub)
1832
1833 :switch:`--files={filename}`
1834 Take as arguments the files listed in text file ``file``.
1835 Text file ``file`` may contain empty lines that are ignored.
1836 Each nonempty line should contain the name of an existing file.
1837 Several such switches may be specified.
1838
1839
1840 .. index:: --output (gnatstub)
1841
1842 :switch:`--output={body-name}`
1843 Body file name. This should be set if the argument file name does
1844 not follow the default GNAT file naming conventions, and the naming
1845 conventions are not specified by a project file. If this switch and
1846 ``-P`` are both omitted, the name for the body will be obtained
1847 according to the default GNAT file naming conventions.
1848
1849
1850 .. index:: --output-dir (gnatstub)
1851
1852 :switch:`--output-dir={dir-name}`
1853 The directory in which to place the output files.
1854 If this switch is not set, the generated library unit body is
1855 placed in the current directory, and generated sununits
1856 in the directory where the argument body is located.
1857
1858
1859 .. index:: --wide-character-encoding (gnatstub)
1860
1861 :switch:`--wide-character-encoding={e}`
1862 Specify the wide character encoding method for the input and output
1863 files. ``e`` is one of the following:
1864
1865 * *8* - UTF-8 encoding
1866
1867 * *b* - Brackets encoding (default value)
1868
1869
1870 .. index:: --quiet (gnatstub)
1871 .. index:: -q (gnatstub)
1872
1873 :switch:`--quiet` / :switch:`-q`
1874 Quiet mode.
1875
1876
1877 .. index:: --verbose (gnatstub)
1878 .. index:: -v (gnatstub)
1879
1880 :switch:`--verbose` / :switch:`-v`
1881 Verbose mode.
1882
1883 Legacy Switches
1884 ^^^^^^^^^^^^^^^
1885
1886 Some switches have a short form, mostly for legacy reasons,
1887 as shown below.
1888
1889 .. index:: -M (gnatstub)
1890
1891 :switch:`-gnatyM{nnn}`
1892 :switch:`--max-line-length={nnn}`
1893
1894 .. index:: -i (gnatstub)
1895
1896 :switch:`-i{nnn}`
1897 :switch:`--indentation={nnn}`
1898
1899 .. index:: -gnaty (gnatstub)
1900
1901 :switch:`-gnaty{nnn}`
1902 :switch:`--indentation={nnn}`
1903
1904 .. index:: -f (gnatstub)
1905
1906 :switch:`-f`
1907 :switch:`--force`
1908
1909 .. index:: -gnatyo (gnatstub)
1910
1911 :switch:`-gnatyo`
1912 :switch:`--alphabetical-order`
1913
1914 .. index:: -hg (gnatstub)
1915
1916 :switch:`-hg`
1917 :switch:`--comment-header-sample`
1918
1919 .. index:: -hs (gnatstub)
1920
1921 :switch:`-hs`
1922 :switch:`--comment-header-spec`
1923
1924 .. index:: -o (gnatstub)
1925
1926 :switch:`-o {output-file}`
1927 :switch:`--output={output-file}`
1928
1929 .. index:: -dir (gnatstub)
1930
1931 :switch:`-dir {dir-name}`
1932 :switch:`--output-dir={dir-name}`
1933
1934 .. index:: -W (gnatstub)
1935
1936 :switch:`-W{e}`
1937 :switch:`--wide-character-encoding={e}`
1938
1939 .. index:: -files (gnatstub)
1940
1941 :switch:`-files {filename}`
1942 :switch:`--files={filename}`
1943
1944
1945 .. only:: PRO or GPL
1946
1947 .. _The_Backtrace_Symbolizer_gnatsymbolize:
1948
1949 Translating Code Addresses into Source Locations with ``gnatsymbolize``
1950 =======================================================================
1951
1952 .. index:: ! gnatsymbolize
1953
1954 ``gnatsymbolize`` is a program which translates addresses into
1955 their corresponding filename, line number, and function names.
1956
1957 Running ``gnatsymbolize``
1958 -------------------------
1959
1960 ::
1961
1962 $ gnatsymbolize [ switches ] filename [ addresses ]
1963
1964 For instance, consider the following Ada program:
1965
1966 .. code-block:: ada
1967
1968 package Pck is
1969 Global_Val : Integer := 0;
1970 procedure Call_Me_First;
1971 end Pck;
1972
1973 with GNAT.IO; use GNAT.IO;
1974 with GNAT.Traceback; use GNAT.Traceback;
1975 with GNAT.Debug_Utilities;
1976
1977 package body Pck is
1978 procedure Call_Me_Third is
1979 TB : Tracebacks_Array (1 .. 5);
1980 TB_len : Natural;
1981 begin
1982 Global_Val := Global_Val + 1;
1983
1984 Call_Chain (TB, TB_Len);
1985 for K in 1 .. TB_Len loop
1986 Put_Line (GNAT.Debug_Utilities.Image_C (TB (K)));
1987 end loop;
1988 end Call_Me_Third;
1989
1990 procedure Call_Me_Second is
1991 begin
1992 Call_Me_Third;
1993 end Call_Me_Second;
1994
1995 procedure Call_Me_First is
1996 begin
1997 Call_Me_Second;
1998 end Call_Me_First;
1999 end Pck;
2000
2001 with GNAT.IO; use GNAT.IO;
2002 with GNAT.Debug_Utilities;
2003 with GNAT.Traceback;
2004 with System;
2005
2006 with Pck; use Pck;
2007
2008 procedure Foo is
2009 LA : constant System.Address := \
2010 GNAT.Traceback.Executable_Load_Address;
2011
2012 use type System.Address;
2013
2014 begin
2015 if LA /= System.Null_Address then
2016 Put_Line ("Load address: " & GNAT.Debug_Utilities.Image_C (LA));
2017 end if;
2018
2019 Global_Val := 123;
2020 Call_Me_First;
2021 end Foo;
2022
2023 This program, when built and run, prints a list of addresses which
2024 correspond to the traceback when inside function ``Call_Me_Third``.
2025 For instance, on x86-64 GNU/Linux:
2026
2027 ::
2028
2029 $ gnatmake -g -q foo.adb
2030 $ ./foo
2031 Load address: 0x00005586C9D7D000
2032 0x00005586C9D81105
2033 0x00005586C9D8119B
2034 0x00005586C9D811A7
2035 0x00005586C9D8128C
2036 0x00005586C9D81069
2037
2038 ``gnatsymbolize`` can be used to translate those addresses into
2039 code locations as follow:
2040
2041 ::
2042
2043 $ gnatsymbolize --load foo 0x00005586C9D7D000 0x00005586C9D81105 \
2044 0x00005586C9D8119B 0x00005586C9D811A7 0x00005586C9D8128C \
2045 0x00005586C9D81069
2046 0x5586c9d81105 Pck.Call_Me_Third at pck.adb:12
2047 0x5586c9d8119b Pck.Call_Me_Second at pck.adb:20
2048 0x5586c9d811a7 Pck.Call_Me_First at pck.adb:25
2049 0x5586c9d8128c Foo at foo.adb:6
2050 0x5586c9d81069 Main at b~foo.adb:199
2051
2052 Switches for ``gnatsymbolize``
2053 ------------------------------
2054
2055 ``gnatsymbolize`` recognizes the following switches:
2056
2057 .. index:: --help (gnatsymbolize)
2058
2059 :switch:`--help`
2060 Display the program's usage, and then exit, disregarding all other
2061 options.
2062
2063 :switch:`--cache`
2064 Read the symbolic information from the executable and cache them
2065 in memory in order to accelerate the translation of each address
2066 into a symbolic location.
2067
2068 Depending on the size of the executable and the number of addresses
2069 to translate, this may not always make ``gnatsymbolize`` faster
2070 overall.
2071
2072 :switch:`--dump`
2073 If :switch:`--cache` is used, dump the contents of the cache on
2074 Standard Output. Has no effect otherwise.
2075
2076 :switch:`--count={N}`
2077 Compute the symbolic traceback ``N`` times in a row. This option
2078 is mostly useful for measuring the performance of ``gnatsymbolize``,
2079 particularly in the case where the cache is being used.
2080
2081 :switch:`--load`
2082 Interpret the first address as the load address of the executable.
2083 This is needed for position-independent executables on Linux and Windows.
2084
2085 Requirements for Correct Operation
2086 ----------------------------------
2087
2088 The translation is performed by reading the DWARF debugging
2089 information produced by the compiler for each unit. All units
2090 for which the translation is to be done must therefore be compiled
2091 such that DWARF debugging information is produced. In most cases,
2092 this is done by simply compiling with ``-g``.
2093
2094 This program provides a functionality similar to ``addr2line``.
2095 It has fewer options to tailor its output, but has been designed
2096 to require fewer of the DWARF sections to be present in the
2097 executable. In particular, it works for code compiled with ``-g1``.
2098
2099
2100 .. only:: PRO or GPL
2101
2102 .. _Using_Project_Files_with_GNAT_Tools:
2103
2104 Using Project Files with GNAT Tools
2105 ===================================
2106
2107 This section describes how project files can be used in conjunction
2108 with a number of GNAT tools.
2109 For a comprehensive description of project files and the overall
2110 GNAT Project Manager facility, please refer to the
2111 *GNAT Project Manager* chapter in the
2112 *GPRbuild and GPR Companion Tools User's Guide*.
2113
2114 .. index:: Project-aware tool
2115
2116 If a tool can take a project file as an option and extract the needed
2117 information, such a tool is called a *project-aware* tool.
2118
2119 .. _Switches_Related_to_Project_Files:
2120
2121 Switches Related to Project Files
2122 ---------------------------------
2123
2124 The following switches are used by the project-aware GNAT tools:
2125
2126 :switch:`-P{project_file}`
2127 Indicates the name of the project file whose source files are to
2128 be processed. The exact set of sources depends on other options
2129 specified, see below.
2130
2131 :switch:`-U`
2132 If a project file is supplied, say for project ``proj``,
2133 but no sources are specified for ``proj`` (either by a
2134 project attribute or through a tool option that provides a list
2135 of the files to be used), process all the source files
2136 from projects imported either directly or indirectly by ``proj``.
2137 Otherwise this option has no effect.
2138
2139 :switch:`-U {source_file}`
2140 Similar to :switch:`-U`, but if no sources are specified then
2141 process only those source files for units in the closure of
2142 the Ada source contained in ``source_file``. Note that this option
2143 expects the source file name but not the Ada unit name as its
2144 parameter.
2145
2146 :switch:`-X{name}={val}`
2147 Indicates that the external variable ``name`` in the project has the
2148 value ``val``. Has no effect if no project has been specified.
2149
2150 :switch:`--subdirs={dir}`
2151 Use the ``dir`` subdirectory of the project's object directory (or the ``dir``
2152 subdirectory of the project file directory if the project does not specify
2153 an object directory) for tool output files. Has no effect if no project
2154 has been specified or if :switch:`--no-objects-dir` is specified.
2155
2156 :switch:`--no-objects-dir`
2157 Place all the result files into the current directory (i.e., the directory
2158 from which the tool invocation command is issued) instead of the project's
2159 object directory. Has no effect if no project has been specified.
2160
2161 :switch:`-eL`
2162 Follow all symbolic links when processing project files.
2163
2164 If a project file is specified and there is neither a :switch:`-U` option,
2165 nor a :switch:`-U {main_unit}` option, nor some other explicit option to
2166 specify the source files, then the sources to be processed are the
2167 immediate sources of the specified project (i.e., the source files directly
2168 defined by that project, either implicitly by residing in the project
2169 source directories, or explicitly through any of the source-related
2170 attributes).
2171
2172 .. _Tool-specific_packages_in_project files:
2173
2174 Tool-specific packages in project files
2175 ---------------------------------------
2176
2177 Each project-aware tool may have a corresponding package in a project file;
2178 the package names are given elsewhere in this manual, in the sections that describe
2179 the respective tools.
2180
2181 A tool-specific package in a project file may define the ``Default_Switches``
2182 attribute indexed by "ada" (as language name). The value of this attribute
2183 is a list of switches that will be supplied at tool invocation.
2184 Project-specific switches cannot be specified through this attribute.