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