| 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. |