1.. |with| replace:: *with* 2.. |withs| replace:: *with*\ s 3.. |withed| replace:: *with*\ ed 4.. |withing| replace:: *with*\ ing 5 6.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit 7 8.. role:: switch(samp) 9 10.. _Building_Executable_Programs_With_GNAT: 11 12************************************** 13Building Executable Programs with GNAT 14************************************** 15 16This chapter describes first the gnatmake tool 17(:ref:`The_GNAT_Make_Program_gnatmake`), 18which automatically determines the set of sources 19needed by an Ada compilation unit and executes the necessary 20(re)compilations, binding and linking. 21It also explains how to use each tool individually: the 22compiler (gcc, see :ref:`Compiling_with_gcc`), 23binder (gnatbind, see :ref:`Binding_with_gnatbind`), 24and linker (gnatlink, see :ref:`Linking_with_gnatlink`) 25to build executable programs. 26Finally, this chapter provides examples of 27how to make use of the general GNU make mechanism 28in a GNAT context (see :ref:`Using_the_GNU_make_Utility`). 29 30.. only:: PRO or GPL 31 32 For building large systems with components possibly written 33 in different languages (such as Ada, C, C++ and Fortran) 34 and organized into subsystems and libraries, the GPRbuild 35 tool can be used. This tool, and the Project Manager 36 facility that it is based upon, is described in 37 *GPRbuild and GPR Companion Tools User's Guide*. 38 39 40.. _The_GNAT_Make_Program_gnatmake: 41 42Building with ``gnatmake`` 43========================== 44 45.. index:: gnatmake 46 47A typical development cycle when working on an Ada program consists of 48the following steps: 49 50#. Edit some sources to fix bugs; 51 52#. Add enhancements; 53 54#. Compile all sources affected; 55 56#. Rebind and relink; and 57 58#. Test. 59 60.. index:: Dependency rules (compilation) 61 62The third step in particular can be tricky, because not only do the modified 63files have to be compiled, but any files depending on these files must also be 64recompiled. The dependency rules in Ada can be quite complex, especially 65in the presence of overloading, ``use`` clauses, generics and inlined 66subprograms. 67 68``gnatmake`` automatically takes care of the third and fourth steps 69of this process. It determines which sources need to be compiled, 70compiles them, and binds and links the resulting object files. 71 72Unlike some other Ada make programs, the dependencies are always 73accurately recomputed from the new sources. The source based approach of 74the GNAT compilation model makes this possible. This means that if 75changes to the source program cause corresponding changes in 76dependencies, they will always be tracked exactly correctly by 77``gnatmake``. 78 79Note that for advanced forms of project structure, we recommend creating 80a project file as explained in the *GNAT_Project_Manager* chapter in the 81*GPRbuild User's Guide*, and using the 82``gprbuild`` tool which supports building with project files and works similarly 83to ``gnatmake``. 84 85.. _Running_gnatmake: 86 87Running ``gnatmake`` 88-------------------- 89 90The usual form of the ``gnatmake`` command is 91 92.. code-block:: sh 93 94 $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>] 95 96The only required argument is one ``file_name``, which specifies 97a compilation unit that is a main program. Several ``file_names`` can be 98specified: this will result in several executables being built. 99If ``switches`` are present, they can be placed before the first 100``file_name``, between ``file_names`` or after the last ``file_name``. 101If ``mode_switches`` are present, they must always be placed after 102the last ``file_name`` and all ``switches``. 103 104If you are using standard file extensions (:file:`.adb` and 105:file:`.ads`), then the 106extension may be omitted from the ``file_name`` arguments. However, if 107you are using non-standard extensions, then it is required that the 108extension be given. A relative or absolute directory path can be 109specified in a ``file_name``, in which case, the input source file will 110be searched for in the specified directory only. Otherwise, the input 111source file will first be searched in the directory where 112``gnatmake`` was invoked and if it is not found, it will be search on 113the source path of the compiler as described in 114:ref:`Search_Paths_and_the_Run-Time_Library_RTL`. 115 116All ``gnatmake`` output (except when you specify :switch:`-M`) is sent to 117:file:`stderr`. The output produced by the 118:switch:`-M` switch is sent to :file:`stdout`. 119 120 121.. _Switches_for_gnatmake: 122 123Switches for ``gnatmake`` 124------------------------- 125 126You may specify any of the following switches to ``gnatmake``: 127 128 129.. index:: --version (gnatmake) 130 131:switch:`--version` 132 Display Copyright and version, then exit disregarding all other options. 133 134 135.. index:: --help (gnatmake) 136 137:switch:`--help` 138 If ``--version`` was not used, display usage, then exit disregarding 139 all other options. 140 141 142.. index:: --GCC=compiler_name (gnatmake) 143 144:switch:`--GCC={compiler_name}` 145 Program used for compiling. The default is ``gcc``. You need to use 146 quotes around ``compiler_name`` if ``compiler_name`` contains 147 spaces or other separator characters. 148 As an example ``--GCC="foo -x -y"`` 149 will instruct ``gnatmake`` to use ``foo -x -y`` as your 150 compiler. A limitation of this syntax is that the name and path name of 151 the executable itself must not include any embedded spaces. Note that 152 switch :switch:`-c` is always inserted after your command name. Thus in the 153 above example the compiler command that will be used by ``gnatmake`` 154 will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are 155 used, only the last ``compiler_name`` is taken into account. However, 156 all the additional switches are also taken into account. Thus, 157 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to 158 ``--GCC="bar -x -y -z -t"``. 159 160 161.. index:: --GNATBIND=binder_name (gnatmake) 162 163:switch:`--GNATBIND={binder_name}` 164 Program used for binding. The default is ``gnatbind``. You need to 165 use quotes around ``binder_name`` if ``binder_name`` contains spaces 166 or other separator characters. 167 As an example ``--GNATBIND="bar -x -y"`` 168 will instruct ``gnatmake`` to use ``bar -x -y`` as your 169 binder. Binder switches that are normally appended by ``gnatmake`` 170 to ``gnatbind`` are now appended to the end of ``bar -x -y``. 171 A limitation of this syntax is that the name and path name of the executable 172 itself must not include any embedded spaces. 173 174.. index:: --GNATLINK=linker_name (gnatmake) 175 176:switch:`--GNATLINK={linker_name}` 177 Program used for linking. The default is ``gnatlink``. You need to 178 use quotes around ``linker_name`` if ``linker_name`` contains spaces 179 or other separator characters. 180 As an example ``--GNATLINK="lan -x -y"`` 181 will instruct ``gnatmake`` to use ``lan -x -y`` as your 182 linker. Linker switches that are normally appended by ``gnatmake`` to 183 ``gnatlink`` are now appended to the end of ``lan -x -y``. 184 A limitation of this syntax is that the name and path name of the executable 185 itself must not include any embedded spaces. 186 187:switch:`--create-map-file` 188 When linking an executable, create a map file. The name of the map file 189 has the same name as the executable with extension ".map". 190 191:switch:`--create-map-file={mapfile}` 192 When linking an executable, create a map file with the specified name. 193 194.. index:: --create-missing-dirs (gnatmake) 195 196:switch:`--create-missing-dirs` 197 When using project files (:switch:`-P{project}`), automatically create 198 missing object directories, library directories and exec 199 directories. 200 201:switch:`--single-compile-per-obj-dir` 202 Disallow simultaneous compilations in the same object directory when 203 project files are used. 204 205:switch:`--subdirs={subdir}` 206 Actual object directory of each project file is the subdirectory subdir of the 207 object directory specified or defaulted in the project file. 208 209:switch:`--unchecked-shared-lib-imports` 210 By default, shared library projects are not allowed to import static library 211 projects. When this switch is used on the command line, this restriction is 212 relaxed. 213 214:switch:`--source-info={source info file}` 215 Specify a source info file. This switch is active only when project files 216 are used. If the source info file is specified as a relative path, then it is 217 relative to the object directory of the main project. If the source info file 218 does not exist, then after the Project Manager has successfully parsed and 219 processed the project files and found the sources, it creates the source info 220 file. If the source info file already exists and can be read successfully, 221 then the Project Manager will get all the needed information about the sources 222 from the source info file and will not look for them. This reduces the time 223 to process the project files, especially when looking for sources that take a 224 long time. If the source info file exists but cannot be parsed successfully, 225 the Project Manager will attempt to recreate it. If the Project Manager fails 226 to create the source info file, a message is issued, but gnatmake does not 227 fail. ``gnatmake`` "trusts" the source info file. This means that 228 if the source files have changed (addition, deletion, moving to a different 229 source directory), then the source info file need to be deleted and recreated. 230 231 232.. index:: -a (gnatmake) 233 234:switch:`-a` 235 Consider all files in the make process, even the GNAT internal system 236 files (for example, the predefined Ada library files), as well as any 237 locked files. Locked files are files whose ALI file is write-protected. 238 By default, 239 ``gnatmake`` does not check these files, 240 because the assumption is that the GNAT internal files are properly up 241 to date, and also that any write protected ALI files have been properly 242 installed. Note that if there is an installation problem, such that one 243 of these files is not up to date, it will be properly caught by the 244 binder. 245 You may have to specify this switch if you are working on GNAT 246 itself. The switch ``-a`` is also useful 247 in conjunction with ``-f`` 248 if you need to recompile an entire application, 249 including run-time files, using special configuration pragmas, 250 such as a ``Normalize_Scalars`` pragma. 251 252 By default 253 ``gnatmake -a`` compiles all GNAT 254 internal files with 255 ``gcc -c -gnatpg`` rather than ``gcc -c``. 256 257 258.. index:: -b (gnatmake) 259 260:switch:`-b` 261 Bind only. Can be combined with :switch:`-c` to do 262 compilation and binding, but no link. 263 Can be combined with :switch:`-l` 264 to do binding and linking. When not combined with 265 :switch:`-c` 266 all the units in the closure of the main program must have been previously 267 compiled and must be up to date. The root unit specified by ``file_name`` 268 may be given without extension, with the source extension or, if no GNAT 269 Project File is specified, with the ALI file extension. 270 271 272.. index:: -c (gnatmake) 273 274:switch:`-c` 275 Compile only. Do not perform binding, except when :switch:`-b` 276 is also specified. Do not perform linking, except if both 277 :switch:`-b` and 278 :switch:`-l` are also specified. 279 If the root unit specified by ``file_name`` is not a main unit, this is the 280 default. Otherwise ``gnatmake`` will attempt binding and linking 281 unless all objects are up to date and the executable is more recent than 282 the objects. 283 284 285.. index:: -C (gnatmake) 286 287:switch:`-C` 288 Use a temporary mapping file. A mapping file is a way to communicate 289 to the compiler two mappings: from unit names to file names (without 290 any directory information) and from file names to path names (with 291 full directory information). A mapping file can make the compiler's 292 file searches faster, especially if there are many source directories, 293 or the sources are read over a slow network connection. If 294 :switch:`-P` is used, a mapping file is always used, so 295 :switch:`-C` is unnecessary; in this case the mapping file 296 is initially populated based on the project file. If 297 :switch:`-C` is used without 298 :switch:`-P`, 299 the mapping file is initially empty. Each invocation of the compiler 300 will add any newly accessed sources to the mapping file. 301 302 303.. index:: -C= (gnatmake) 304 305:switch:`-C={file}` 306 Use a specific mapping file. The file, specified as a path name (absolute or 307 relative) by this switch, should already exist, otherwise the switch is 308 ineffective. The specified mapping file will be communicated to the compiler. 309 This switch is not compatible with a project file 310 (-P`file`) or with multiple compiling processes 311 (-jnnn, when nnn is greater than 1). 312 313 314.. index:: -d (gnatmake) 315 316:switch:`-d` 317 Display progress for each source, up to date or not, as a single line: 318 319 :: 320 321 completed x out of y (zz%) 322 323 If the file needs to be compiled this is displayed after the invocation of 324 the compiler. These lines are displayed even in quiet output mode. 325 326 327.. index:: -D (gnatmake) 328 329:switch:`-D {dir}` 330 Put all object files and ALI file in directory ``dir``. 331 If the :switch:`-D` switch is not used, all object files 332 and ALI files go in the current working directory. 333 334 This switch cannot be used when using a project file. 335 336 337.. index:: -eI (gnatmake) 338 339:switch:`-eI{nnn}` 340 Indicates that the main source is a multi-unit source and the rank of the unit 341 in the source file is nnn. nnn needs to be a positive number and a valid 342 index in the source. This switch cannot be used when ``gnatmake`` is 343 invoked for several mains. 344 345 346.. index:: -eL (gnatmake) 347.. index:: symbolic links 348 349:switch:`-eL` 350 Follow all symbolic links when processing project files. 351 This should be used if your project uses symbolic links for files or 352 directories, but is not needed in other cases. 353 354 .. index:: naming scheme 355 356 This also assumes that no directory matches the naming scheme for files (for 357 instance that you do not have a directory called "sources.ads" when using the 358 default GNAT naming scheme). 359 360 When you do not have to use this switch (i.e., by default), gnatmake is able to 361 save a lot of system calls (several per source file and object file), which 362 can result in a significant speed up to load and manipulate a project file, 363 especially when using source files from a remote system. 364 365 366.. index:: -eS (gnatmake) 367 368:switch:`-eS` 369 Output the commands for the compiler, the binder and the linker 370 on standard output, 371 instead of standard error. 372 373 374.. index:: -f (gnatmake) 375 376:switch:`-f` 377 Force recompilations. Recompile all sources, even though some object 378 files may be up to date, but don't recompile predefined or GNAT internal 379 files or locked files (files with a write-protected ALI file), 380 unless the :switch:`-a` switch is also specified. 381 382 383.. index:: -F (gnatmake) 384 385:switch:`-F` 386 When using project files, if some errors or warnings are detected during 387 parsing and verbose mode is not in effect (no use of switch 388 -v), then error lines start with the full path name of the project 389 file, rather than its simple file name. 390 391 392.. index:: -g (gnatmake) 393 394:switch:`-g` 395 Enable debugging. This switch is simply passed to the compiler and to the 396 linker. 397 398 399.. index:: -i (gnatmake) 400 401:switch:`-i` 402 In normal mode, ``gnatmake`` compiles all object files and ALI files 403 into the current directory. If the :switch:`-i` switch is used, 404 then instead object files and ALI files that already exist are overwritten 405 in place. This means that once a large project is organized into separate 406 directories in the desired manner, then ``gnatmake`` will automatically 407 maintain and update this organization. If no ALI files are found on the 408 Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`), 409 the new object and ALI files are created in the 410 directory containing the source being compiled. If another organization 411 is desired, where objects and sources are kept in different directories, 412 a useful technique is to create dummy ALI files in the desired directories. 413 When detecting such a dummy file, ``gnatmake`` will be forced to 414 recompile the corresponding source file, and it will be put the resulting 415 object and ALI files in the directory where it found the dummy file. 416 417 418.. index:: -j (gnatmake) 419.. index:: Parallel make 420 421:switch:`-j{n}` 422 Use ``n`` processes to carry out the (re)compilations. On a multiprocessor 423 machine compilations will occur in parallel. If ``n`` is 0, then the 424 maximum number of parallel compilations is the number of core processors 425 on the platform. In the event of compilation errors, messages from various 426 compilations might get interspersed (but ``gnatmake`` will give you the 427 full ordered list of failing compiles at the end). If this is problematic, 428 rerun the make process with n set to 1 to get a clean list of messages. 429 430 431.. index:: -k (gnatmake) 432 433:switch:`-k` 434 Keep going. Continue as much as possible after a compilation error. To 435 ease the programmer's task in case of compilation errors, the list of 436 sources for which the compile fails is given when ``gnatmake`` 437 terminates. 438 439 If ``gnatmake`` is invoked with several :file:`file_names` and with this 440 switch, if there are compilation errors when building an executable, 441 ``gnatmake`` will not attempt to build the following executables. 442 443 444.. index:: -l (gnatmake) 445 446:switch:`-l` 447 Link only. Can be combined with :switch:`-b` to binding 448 and linking. Linking will not be performed if combined with 449 :switch:`-c` 450 but not with :switch:`-b`. 451 When not combined with :switch:`-b` 452 all the units in the closure of the main program must have been previously 453 compiled and must be up to date, and the main program needs to have been bound. 454 The root unit specified by ``file_name`` 455 may be given without extension, with the source extension or, if no GNAT 456 Project File is specified, with the ALI file extension. 457 458 459.. index:: -m (gnatmake) 460 461:switch:`-m` 462 Specify that the minimum necessary amount of recompilations 463 be performed. In this mode ``gnatmake`` ignores time 464 stamp differences when the only 465 modifications to a source file consist in adding/removing comments, 466 empty lines, spaces or tabs. This means that if you have changed the 467 comments in a source file or have simply reformatted it, using this 468 switch will tell ``gnatmake`` not to recompile files that depend on it 469 (provided other sources on which these files depend have undergone no 470 semantic modifications). Note that the debugging information may be 471 out of date with respect to the sources if the :switch:`-m` switch causes 472 a compilation to be switched, so the use of this switch represents a 473 trade-off between compilation time and accurate debugging information. 474 475 476.. index:: Dependencies, producing list 477.. index:: -M (gnatmake) 478 479:switch:`-M` 480 Check if all objects are up to date. If they are, output the object 481 dependences to :file:`stdout` in a form that can be directly exploited in 482 a :file:`Makefile`. By default, each source file is prefixed with its 483 (relative or absolute) directory name. This name is whatever you 484 specified in the various :switch:`-aI` 485 and :switch:`-I` switches. If you use 486 ``gnatmake -M`` :switch:`-q` 487 (see below), only the source file names, 488 without relative paths, are output. If you just specify the :switch:`-M` 489 switch, dependencies of the GNAT internal system files are omitted. This 490 is typically what you want. If you also specify 491 the :switch:`-a` switch, 492 dependencies of the GNAT internal files are also listed. Note that 493 dependencies of the objects in external Ada libraries (see 494 switch :switch:`-aL{dir}` in the following list) 495 are never reported. 496 497 498.. index:: -n (gnatmake) 499 500:switch:`-n` 501 Don't compile, bind, or link. Checks if all objects are up to date. 502 If they are not, the full name of the first file that needs to be 503 recompiled is printed. 504 Repeated use of this option, followed by compiling the indicated source 505 file, will eventually result in recompiling all required units. 506 507 508.. index:: -o (gnatmake) 509 510:switch:`-o {exec_name}` 511 Output executable name. The name of the final executable program will be 512 ``exec_name``. If the :switch:`-o` switch is omitted the default 513 name for the executable will be the name of the input file in appropriate form 514 for an executable file on the host system. 515 516 This switch cannot be used when invoking ``gnatmake`` with several 517 :file:`file_names`. 518 519 520.. index:: -p (gnatmake) 521 522:switch:`-p` 523 Same as :switch:`--create-missing-dirs` 524 525.. index:: -P (gnatmake) 526 527:switch:`-P{project}` 528 Use project file ``project``. Only one such switch can be used. 529 530.. -- Comment: 531 :ref:`gnatmake_and_Project_Files`. 532 533 534.. index:: -q (gnatmake) 535 536:switch:`-q` 537 Quiet. When this flag is not set, the commands carried out by 538 ``gnatmake`` are displayed. 539 540 541.. index:: -s (gnatmake) 542 543:switch:`-s` 544 Recompile if compiler switches have changed since last compilation. 545 All compiler switches but -I and -o are taken into account in the 546 following way: 547 orders between different 'first letter' switches are ignored, but 548 orders between same switches are taken into account. For example, 549 :switch:`-O -O2` is different than :switch:`-O2 -O`, but :switch:`-g -O` 550 is equivalent to :switch:`-O -g`. 551 552 This switch is recommended when Integrated Preprocessing is used. 553 554 555.. index:: -u (gnatmake) 556 557:switch:`-u` 558 Unique. Recompile at most the main files. It implies -c. Combined with 559 -f, it is equivalent to calling the compiler directly. Note that using 560 -u with a project file and no main has a special meaning. 561 562.. --Comment 563 (See :ref:`Project_Files_and_Main_Subprograms`.) 564 565 566.. index:: -U (gnatmake) 567 568:switch:`-U` 569 When used without a project file or with one or several mains on the command 570 line, is equivalent to -u. When used with a project file and no main 571 on the command line, all sources of all project files are checked and compiled 572 if not up to date, and libraries are rebuilt, if necessary. 573 574 575.. index:: -v (gnatmake) 576 577:switch:`-v` 578 Verbose. Display the reason for all recompilations ``gnatmake`` 579 decides are necessary, with the highest verbosity level. 580 581 582.. index:: -vl (gnatmake) 583 584:switch:`-vl` 585 Verbosity level Low. Display fewer lines than in verbosity Medium. 586 587 588.. index:: -vm (gnatmake) 589 590:switch:`-vm` 591 Verbosity level Medium. Potentially display fewer lines than in verbosity High. 592 593 594.. index:: -vm (gnatmake) 595 596:switch:`-vh` 597 Verbosity level High. Equivalent to -v. 598 599 600:switch:`-vP{x}` 601 Indicate the verbosity of the parsing of GNAT project files. 602 See :ref:`Switches_Related_to_Project_Files`. 603 604 605.. index:: -x (gnatmake) 606 607:switch:`-x` 608 Indicate that sources that are not part of any Project File may be compiled. 609 Normally, when using Project Files, only sources that are part of a Project 610 File may be compile. When this switch is used, a source outside of all Project 611 Files may be compiled. The ALI file and the object file will be put in the 612 object directory of the main Project. The compilation switches used will only 613 be those specified on the command line. Even when 614 :switch:`-x` is used, mains specified on the 615 command line need to be sources of a project file. 616 617 618:switch:`-X{name}={value}` 619 Indicate that external variable ``name`` has the value ``value``. 620 The Project Manager will use this value for occurrences of 621 ``external(name)`` when parsing the project file. 622 :ref:`Switches_Related_to_Project_Files`. 623 624 625.. index:: -z (gnatmake) 626 627:switch:`-z` 628 No main subprogram. Bind and link the program even if the unit name 629 given on the command line is a package name. The resulting executable 630 will execute the elaboration routines of the package and its closure, 631 then the finalization routines. 632 633 634.. rubric:: GCC switches 635 636Any uppercase or multi-character switch that is not a ``gnatmake`` switch 637is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.) 638 639 640.. rubric:: Source and library search path switches 641 642.. index:: -aI (gnatmake) 643 644:switch:`-aI{dir}` 645 When looking for source files also look in directory ``dir``. 646 The order in which source files search is undertaken is 647 described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`. 648 649 650.. index:: -aL (gnatmake) 651 652:switch:`-aL{dir}` 653 Consider ``dir`` as being an externally provided Ada library. 654 Instructs ``gnatmake`` to skip compilation units whose :file:`.ALI` 655 files have been located in directory ``dir``. This allows you to have 656 missing bodies for the units in ``dir`` and to ignore out of date bodies 657 for the same units. You still need to specify 658 the location of the specs for these units by using the switches 659 :switch:`-aI{dir}` or :switch:`-I{dir}`. 660 Note: this switch is provided for compatibility with previous versions 661 of ``gnatmake``. The easier method of causing standard libraries 662 to be excluded from consideration is to write-protect the corresponding 663 ALI files. 664 665 666.. index:: -aO (gnatmake) 667 668:switch:`-aO{dir}` 669 When searching for library and object files, look in directory 670 ``dir``. The order in which library files are searched is described in 671 :ref:`Search_Paths_for_gnatbind`. 672 673 674.. index:: Search paths, for gnatmake 675.. index:: -A (gnatmake) 676 677:switch:`-A{dir}` 678 Equivalent to :switch:`-aL{dir}` :switch:`-aI{dir}`. 679 680 681 .. index:: -I (gnatmake) 682 683:switch:`-I{dir}` 684 Equivalent to :switch:`-aO{dir} -aI{dir}`. 685 686 687.. index:: -I- (gnatmake) 688.. index:: Source files, suppressing search 689 690:switch:`-I-` 691 Do not look for source files in the directory containing the source 692 file named in the command line. 693 Do not look for ALI or object files in the directory 694 where ``gnatmake`` was invoked. 695 696 697.. index:: -L (gnatmake) 698.. index:: Linker libraries 699 700:switch:`-L{dir}` 701 Add directory ``dir`` to the list of directories in which the linker 702 will search for libraries. This is equivalent to 703 :switch:`-largs` :switch:`-L{dir}`. 704 Furthermore, under Windows, the sources pointed to by the libraries path 705 set in the registry are not searched for. 706 707 708.. index:: -nostdinc (gnatmake) 709 710:switch:`-nostdinc` 711 Do not look for source files in the system default directory. 712 713 714.. index:: -nostdlib (gnatmake) 715 716:switch:`-nostdlib` 717 Do not look for library files in the system default directory. 718 719 720.. index:: --RTS (gnatmake) 721 722:switch:`--RTS={rts-path}` 723 Specifies the default location of the runtime library. GNAT looks for the 724 runtime 725 in the following directories, and stops as soon as a valid runtime is found 726 (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or 727 :file:`ada_object_path` present): 728 729 * *<current directory>/$rts_path* 730 731 * *<default-search-dir>/$rts_path* 732 733 * *<default-search-dir>/rts-$rts_path* 734 735 * The selected path is handled like a normal RTS path. 736 737 738.. _Mode_Switches_for_gnatmake: 739 740Mode Switches for ``gnatmake`` 741------------------------------ 742 743The mode switches (referred to as ``mode_switches``) allow the 744inclusion of switches that are to be passed to the compiler itself, the 745binder or the linker. The effect of a mode switch is to cause all 746subsequent switches up to the end of the switch list, or up to the next 747mode switch, to be interpreted as switches to be passed on to the 748designated component of GNAT. 749 750.. index:: -cargs (gnatmake) 751 752:switch:`-cargs {switches}` 753 Compiler switches. Here ``switches`` is a list of switches 754 that are valid switches for ``gcc``. They will be passed on to 755 all compile steps performed by ``gnatmake``. 756 757 758.. index:: -bargs (gnatmake) 759 760:switch:`-bargs {switches}` 761 Binder switches. Here ``switches`` is a list of switches 762 that are valid switches for ``gnatbind``. They will be passed on to 763 all bind steps performed by ``gnatmake``. 764 765 766.. index:: -largs (gnatmake) 767 768:switch:`-largs {switches}` 769 Linker switches. Here ``switches`` is a list of switches 770 that are valid switches for ``gnatlink``. They will be passed on to 771 all link steps performed by ``gnatmake``. 772 773 774.. index:: -margs (gnatmake) 775 776:switch:`-margs {switches}` 777 Make switches. The switches are directly interpreted by ``gnatmake``, 778 regardless of any previous occurrence of :switch:`-cargs`, :switch:`-bargs` 779 or :switch:`-largs`. 780 781 782.. _Notes_on_the_Command_Line: 783 784Notes on the Command Line 785------------------------- 786 787This section contains some additional useful notes on the operation 788of the ``gnatmake`` command. 789 790.. index:: Recompilation (by gnatmake) 791 792* If ``gnatmake`` finds no ALI files, it recompiles the main program 793 and all other units required by the main program. 794 This means that ``gnatmake`` 795 can be used for the initial compile, as well as during subsequent steps of 796 the development cycle. 797 798* If you enter ``gnatmake foo.adb``, where ``foo`` 799 is a subunit or body of a generic unit, ``gnatmake`` recompiles 800 :file:`foo.adb` (because it finds no ALI) and stops, issuing a 801 warning. 802 803* In ``gnatmake`` the switch :switch:`-I` 804 is used to specify both source and 805 library file paths. Use :switch:`-aI` 806 instead if you just want to specify 807 source paths only and :switch:`-aO` 808 if you want to specify library paths 809 only. 810 811* ``gnatmake`` will ignore any files whose ALI file is write-protected. 812 This may conveniently be used to exclude standard libraries from 813 consideration and in particular it means that the use of the 814 :switch:`-f` switch will not recompile these files 815 unless :switch:`-a` is also specified. 816 817* ``gnatmake`` has been designed to make the use of Ada libraries 818 particularly convenient. Assume you have an Ada library organized 819 as follows: *obj-dir* contains the objects and ALI files for 820 of your Ada compilation units, 821 whereas *include-dir* contains the 822 specs of these units, but no bodies. Then to compile a unit 823 stored in ``main.adb``, which uses this Ada library you would just type: 824 825 .. code-block:: sh 826 827 $ gnatmake -aI`include-dir` -aL`obj-dir` main 828 829* Using ``gnatmake`` along with the :switch:`-m (minimal recompilation)` 830 switch provides a mechanism for avoiding unnecessary recompilations. Using 831 this switch, 832 you can update the comments/format of your 833 source files without having to recompile everything. Note, however, that 834 adding or deleting lines in a source files may render its debugging 835 info obsolete. If the file in question is a spec, the impact is rather 836 limited, as that debugging info will only be useful during the 837 elaboration phase of your program. For bodies the impact can be more 838 significant. In all events, your debugger will warn you if a source file 839 is more recent than the corresponding object, and alert you to the fact 840 that the debugging information may be out of date. 841 842 843.. _How_gnatmake_Works: 844 845How ``gnatmake`` Works 846---------------------- 847 848Generally ``gnatmake`` automatically performs all necessary 849recompilations and you don't need to worry about how it works. However, 850it may be useful to have some basic understanding of the ``gnatmake`` 851approach and in particular to understand how it uses the results of 852previous compilations without incorrectly depending on them. 853 854First a definition: an object file is considered *up to date* if the 855corresponding ALI file exists and if all the source files listed in the 856dependency section of this ALI file have time stamps matching those in 857the ALI file. This means that neither the source file itself nor any 858files that it depends on have been modified, and hence there is no need 859to recompile this file. 860 861``gnatmake`` works by first checking if the specified main unit is up 862to date. If so, no compilations are required for the main unit. If not, 863``gnatmake`` compiles the main program to build a new ALI file that 864reflects the latest sources. Then the ALI file of the main unit is 865examined to find all the source files on which the main program depends, 866and ``gnatmake`` recursively applies the above procedure on all these 867files. 868 869This process ensures that ``gnatmake`` only trusts the dependencies 870in an existing ALI file if they are known to be correct. Otherwise it 871always recompiles to determine a new, guaranteed accurate set of 872dependencies. As a result the program is compiled 'upside down' from what may 873be more familiar as the required order of compilation in some other Ada 874systems. In particular, clients are compiled before the units on which 875they depend. The ability of GNAT to compile in any order is critical in 876allowing an order of compilation to be chosen that guarantees that 877``gnatmake`` will recompute a correct set of new dependencies if 878necessary. 879 880When invoking ``gnatmake`` with several ``file_names``, if a unit is 881imported by several of the executables, it will be recompiled at most once. 882 883Note: when using non-standard naming conventions 884(:ref:`Using_Other_File_Names`), changing through a configuration pragmas 885file the version of a source and invoking ``gnatmake`` to recompile may 886have no effect, if the previous version of the source is still accessible 887by ``gnatmake``. It may be necessary to use the switch 888-f. 889 890 891.. _Examples_of_gnatmake_Usage: 892 893Examples of ``gnatmake`` Usage 894------------------------------ 895 896*gnatmake hello.adb* 897 Compile all files necessary to bind and link the main program 898 :file:`hello.adb` (containing unit ``Hello``) and bind and link the 899 resulting object files to generate an executable file :file:`hello`. 900 901*gnatmake main1 main2 main3* 902 Compile all files necessary to bind and link the main programs 903 :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb` 904 (containing unit ``Main2``) and :file:`main3.adb` 905 (containing unit ``Main3``) and bind and link the resulting object files 906 to generate three executable files :file:`main1`, 907 :file:`main2` and :file:`main3`. 908 909*gnatmake -q Main_Unit -cargs -O2 -bargs -l* 910 Compile all files necessary to bind and link the main program unit 911 ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will 912 be done with optimization level 2 and the order of elaboration will be 913 listed by the binder. ``gnatmake`` will operate in quiet mode, not 914 displaying commands it is executing. 915 916 917.. _Compiling_with_gcc: 918 919Compiling with ``gcc`` 920====================== 921 922This section discusses how to compile Ada programs using the ``gcc`` 923command. It also describes the set of switches 924that can be used to control the behavior of the compiler. 925 926.. _Compiling_Programs: 927 928Compiling Programs 929------------------ 930 931The first step in creating an executable program is to compile the units 932of the program using the ``gcc`` command. You must compile the 933following files: 934 935* the body file (:file:`.adb`) for a library level subprogram or generic 936 subprogram 937 938* the spec file (:file:`.ads`) for a library level package or generic 939 package that has no body 940 941* the body file (:file:`.adb`) for a library level package 942 or generic package that has a body 943 944You need *not* compile the following files 945 946* the spec of a library unit which has a body 947 948* subunits 949 950because they are compiled as part of compiling related units. GNAT 951package specs 952when the corresponding body is compiled, and subunits when the parent is 953compiled. 954 955.. index:: cannot generate code 956 957If you attempt to compile any of these files, you will get one of the 958following error messages (where ``fff`` is the name of the file you 959compiled): 960 961 :: 962 963 cannot generate code for file ``fff`` (package spec) 964 to check package spec, use -gnatc 965 966 cannot generate code for file ``fff`` (missing subunits) 967 to check parent unit, use -gnatc 968 969 cannot generate code for file ``fff`` (subprogram spec) 970 to check subprogram spec, use -gnatc 971 972 cannot generate code for file ``fff`` (subunit) 973 to check subunit, use -gnatc 974 975 976As indicated by the above error messages, if you want to submit 977one of these files to the compiler to check for correct semantics 978without generating code, then use the :switch:`-gnatc` switch. 979 980The basic command for compiling a file containing an Ada unit is: 981 982.. code-block:: sh 983 984 $ gcc -c [switches] <file name> 985 986where ``file name`` is the name of the Ada file (usually 987having an extension :file:`.ads` for a spec or :file:`.adb` for a body). 988You specify the 989:switch:`-c` switch to tell ``gcc`` to compile, but not link, the file. 990The result of a successful compilation is an object file, which has the 991same name as the source file but an extension of :file:`.o` and an Ada 992Library Information (ALI) file, which also has the same name as the 993source file, but with :file:`.ali` as the extension. GNAT creates these 994two output files in the current directory, but you may specify a source 995file in any directory using an absolute or relative path specification 996containing the directory information. 997 998TESTING: the :switch:`--foobar{NN}` switch 999 1000.. index:: gnat1 1001 1002``gcc`` is actually a driver program that looks at the extensions of 1003the file arguments and loads the appropriate compiler. For example, the 1004GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`. 1005These programs are in directories known to the driver program (in some 1006configurations via environment variables you set), but need not be in 1007your path. The ``gcc`` driver also calls the assembler and any other 1008utilities needed to complete the generation of the required object 1009files. 1010 1011It is possible to supply several file names on the same ``gcc`` 1012command. This causes ``gcc`` to call the appropriate compiler for 1013each file. For example, the following command lists two separate 1014files to be compiled: 1015 1016.. code-block:: sh 1017 1018 $ gcc -c x.adb y.adb 1019 1020 1021calls ``gnat1`` (the Ada compiler) twice to compile :file:`x.adb` and 1022:file:`y.adb`. 1023The compiler generates two object files :file:`x.o` and :file:`y.o` 1024and the two ALI files :file:`x.ali` and :file:`y.ali`. 1025 1026Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a 1027list of available ``gcc`` switches. 1028 1029.. _Search_Paths_and_the_Run-Time_Library_RTL: 1030 1031Search Paths and the Run-Time Library (RTL) 1032------------------------------------------- 1033 1034With the GNAT source-based library system, the compiler must be able to 1035find source files for units that are needed by the unit being compiled. 1036Search paths are used to guide this process. 1037 1038The compiler compiles one source file whose name must be given 1039explicitly on the command line. In other words, no searching is done 1040for this file. To find all other source files that are needed (the most 1041common being the specs of units), the compiler examines the following 1042directories, in the following order: 1043 1044* The directory containing the source file of the main unit being compiled 1045 (the file name on the command line). 1046 1047* Each directory named by an :switch:`-I` switch given on the ``gcc`` 1048 command line, in the order given. 1049 1050 .. index:: ADA_PRJ_INCLUDE_FILE 1051 1052* Each of the directories listed in the text file whose name is given 1053 by the :envvar:`ADA_PRJ_INCLUDE_FILE` environment variable. 1054 :envvar:`ADA_PRJ_INCLUDE_FILE` is normally set by gnatmake or by the gnat 1055 driver when project files are used. It should not normally be set 1056 by other means. 1057 1058 .. index:: ADA_INCLUDE_PATH 1059 1060* Each of the directories listed in the value of the 1061 :envvar:`ADA_INCLUDE_PATH` environment variable. 1062 Construct this value 1063 exactly as the :envvar:`PATH` environment variable: a list of directory 1064 names separated by colons (semicolons when working with the NT version). 1065 1066* The content of the :file:`ada_source_path` file which is part of the GNAT 1067 installation tree and is used to store standard libraries such as the 1068 GNAT Run Time Library (RTL) source files. 1069 :ref:`Installing_a_library` 1070 1071Specifying the switch :switch:`-I-` 1072inhibits the use of the directory 1073containing the source file named in the command line. You can still 1074have this directory on your search path, but in this case it must be 1075explicitly requested with a :switch:`-I` switch. 1076 1077Specifying the switch :switch:`-nostdinc` 1078inhibits the search of the default location for the GNAT Run Time 1079Library (RTL) source files. 1080 1081The compiler outputs its object files and ALI files in the current 1082working directory. 1083Caution: The object file can be redirected with the :switch:`-o` switch; 1084however, ``gcc`` and ``gnat1`` have not been coordinated on this 1085so the :file:`ALI` file will not go to the right place. Therefore, you should 1086avoid using the :switch:`-o` switch. 1087 1088.. index:: System.IO 1089 1090The packages ``Ada``, ``System``, and ``Interfaces`` and their 1091children make up the GNAT RTL, together with the simple ``System.IO`` 1092package used in the ``"Hello World"`` example. The sources for these units 1093are needed by the compiler and are kept together in one directory. Not 1094all of the bodies are needed, but all of the sources are kept together 1095anyway. In a normal installation, you need not specify these directory 1096names when compiling or binding. Either the environment variables or 1097the built-in defaults cause these files to be found. 1098 1099In addition to the language-defined hierarchies (``System``, ``Ada`` and 1100``Interfaces``), the GNAT distribution provides a fourth hierarchy, 1101consisting of child units of ``GNAT``. This is a collection of generally 1102useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual` 1103for further details. 1104 1105Besides simplifying access to the RTL, a major use of search paths is 1106in compiling sources from multiple directories. This can make 1107development environments much more flexible. 1108 1109.. _Order_of_Compilation_Issues: 1110 1111Order of Compilation Issues 1112--------------------------- 1113 1114If, in our earlier example, there was a spec for the ``hello`` 1115procedure, it would be contained in the file :file:`hello.ads`; yet this 1116file would not have to be explicitly compiled. This is the result of the 1117model we chose to implement library management. Some of the consequences 1118of this model are as follows: 1119 1120* There is no point in compiling specs (except for package 1121 specs with no bodies) because these are compiled as needed by clients. If 1122 you attempt a useless compilation, you will receive an error message. 1123 It is also useless to compile subunits because they are compiled as needed 1124 by the parent. 1125 1126* There are no order of compilation requirements: performing a 1127 compilation never obsoletes anything. The only way you can obsolete 1128 something and require recompilations is to modify one of the 1129 source files on which it depends. 1130 1131* There is no library as such, apart from the ALI files 1132 (:ref:`The_Ada_Library_Information_Files`, for information on the format 1133 of these files). For now we find it convenient to create separate ALI files, 1134 but eventually the information therein may be incorporated into the object 1135 file directly. 1136 1137* When you compile a unit, the source files for the specs of all units 1138 that it |withs|, all its subunits, and the bodies of any generics it 1139 instantiates must be available (reachable by the search-paths mechanism 1140 described above), or you will receive a fatal error message. 1141 1142.. _Examples: 1143 1144Examples 1145-------- 1146 1147The following are some typical Ada compilation command line examples: 1148 1149.. code-block:: sh 1150 1151 $ gcc -c xyz.adb 1152 1153Compile body in file :file:`xyz.adb` with all default options. 1154 1155.. code-block:: sh 1156 1157 $ gcc -c -O2 -gnata xyz-def.adb 1158 1159Compile the child unit package in file :file:`xyz-def.adb` with extensive 1160optimizations, and pragma ``Assert``/`Debug` statements 1161enabled. 1162 1163.. code-block:: sh 1164 1165 $ gcc -c -gnatc abc-def.adb 1166 1167Compile the subunit in file :file:`abc-def.adb` in semantic-checking-only 1168mode. 1169 1170 1171.. _Switches_for_gcc: 1172 1173Compiler Switches 1174================= 1175 1176The ``gcc`` command accepts switches that control the 1177compilation process. These switches are fully described in this section: 1178first an alphabetical listing of all switches with a brief description, 1179and then functionally grouped sets of switches with more detailed 1180information. 1181 1182More switches exist for GCC than those documented here, especially 1183for specific targets. However, their use is not recommended as 1184they may change code generation in ways that are incompatible with 1185the Ada run-time library, or can cause inconsistencies between 1186compilation units. 1187 1188.. _Alphabetical_List_of_All_Switches: 1189 1190Alphabetical List of All Switches 1191--------------------------------- 1192 1193.. index:: -b (gcc) 1194 1195:switch:`-b {target}` 1196 Compile your program to run on ``target``, which is the name of a 1197 system configuration. You must have a GNAT cross-compiler built if 1198 ``target`` is not the same as your host system. 1199 1200 1201.. index:: -B (gcc) 1202 1203:switch:`-B{dir}` 1204 Load compiler executables (for example, ``gnat1``, the Ada compiler) 1205 from ``dir`` instead of the default location. Only use this switch 1206 when multiple versions of the GNAT compiler are available. 1207 See the "Options for Directory Search" section in the 1208 :title:`Using the GNU Compiler Collection (GCC)` manual for further details. 1209 You would normally use the :switch:`-b` or :switch:`-V` switch instead. 1210 1211.. index:: -c (gcc) 1212 1213:switch:`-c` 1214 Compile. Always use this switch when compiling Ada programs. 1215 1216 Note: for some other languages when using ``gcc``, notably in 1217 the case of C and C++, it is possible to use 1218 use ``gcc`` without a :switch:`-c` switch to 1219 compile and link in one step. In the case of GNAT, you 1220 cannot use this approach, because the binder must be run 1221 and ``gcc`` cannot be used to run the GNAT binder. 1222 1223 1224.. index:: -fcallgraph-info (gcc) 1225 1226:switch:`-fcallgraph-info[=su,da]` 1227 Makes the compiler output callgraph information for the program, on a 1228 per-file basis. The information is generated in the VCG format. It can 1229 be decorated with additional, per-node and/or per-edge information, if a 1230 list of comma-separated markers is additionally specified. When the 1231 ``su`` marker is specified, the callgraph is decorated with stack usage 1232 information; it is equivalent to :switch:`-fstack-usage`. When the ``da`` 1233 marker is specified, the callgraph is decorated with information about 1234 dynamically allocated objects. 1235 1236 1237.. index:: -fdump-scos (gcc) 1238 1239:switch:`-fdump-scos` 1240 Generates SCO (Source Coverage Obligation) information in the ALI file. 1241 This information is used by advanced coverage tools. See unit :file:`SCOs` 1242 in the compiler sources for details in files :file:`scos.ads` and 1243 :file:`scos.adb`. 1244 1245 1246.. index:: -flto (gcc) 1247 1248:switch:`-flto[={n}]` 1249 Enables Link Time Optimization. This switch must be used in conjunction 1250 with the :switch:`-Ox` switches (but not with the :switch:`-gnatn` switch 1251 since it is a full replacement for the latter) and instructs the compiler 1252 to defer most optimizations until the link stage. The advantage of this 1253 approach is that the compiler can do a whole-program analysis and choose 1254 the best interprocedural optimization strategy based on a complete view 1255 of the program, instead of a fragmentary view with the usual approach. 1256 This can also speed up the compilation of big programs and reduce the 1257 size of the executable, compared with a traditional per-unit compilation 1258 with inlining across modules enabled by the :switch:`-gnatn` switch. 1259 The drawback of this approach is that it may require more memory and that 1260 the debugging information generated by -g with it might be hardly usable. 1261 The switch, as well as the accompanying :switch:`-Ox` switches, must be 1262 specified both for the compilation and the link phases. 1263 If the ``n`` parameter is specified, the optimization and final code 1264 generation at link time are executed using ``n`` parallel jobs by 1265 means of an installed ``make`` program. 1266 1267 1268.. index:: -fno-inline (gcc) 1269 1270:switch:`-fno-inline` 1271 Suppresses all inlining, unless requested with pragma ``Inline_Always``. The 1272 effect is enforced regardless of other optimization or inlining switches. 1273 Note that inlining can also be suppressed on a finer-grained basis with 1274 pragma ``No_Inline``. 1275 1276 1277.. index:: -fno-inline-functions (gcc) 1278 1279:switch:`-fno-inline-functions` 1280 Suppresses automatic inlining of subprograms, which is enabled 1281 if :switch:`-O3` is used. 1282 1283 1284.. index:: -fno-inline-small-functions (gcc) 1285 1286:switch:`-fno-inline-small-functions` 1287 Suppresses automatic inlining of small subprograms, which is enabled 1288 if :switch:`-O2` is used. 1289 1290 1291.. index:: -fno-inline-functions-called-once (gcc) 1292 1293:switch:`-fno-inline-functions-called-once` 1294 Suppresses inlining of subprograms local to the unit and called once 1295 from within it, which is enabled if :switch:`-O1` is used. 1296 1297 1298.. index:: -fno-ivopts (gcc) 1299 1300:switch:`-fno-ivopts` 1301 Suppresses high-level loop induction variable optimizations, which are 1302 enabled if :switch:`-O1` is used. These optimizations are generally 1303 profitable but, for some specific cases of loops with numerous uses 1304 of the iteration variable that follow a common pattern, they may end 1305 up destroying the regularity that could be exploited at a lower level 1306 and thus producing inferior code. 1307 1308 1309.. index:: -fno-strict-aliasing (gcc) 1310 1311:switch:`-fno-strict-aliasing` 1312 Causes the compiler to avoid assumptions regarding non-aliasing 1313 of objects of different types. See 1314 :ref:`Optimization_and_Strict_Aliasing` for details. 1315 1316 1317.. index:: -fno-strict-overflow (gcc) 1318 1319:switch:`-fno-strict-overflow` 1320 Causes the compiler to avoid assumptions regarding the rules of signed 1321 integer overflow. These rules specify that signed integer overflow will 1322 result in a Constraint_Error exception at run time and are enforced in 1323 default mode by the compiler, so this switch should not be necessary in 1324 normal operating mode. It might be useful in conjunction with :switch:`-gnato0` 1325 for very peculiar cases of low-level programming. 1326 1327 1328.. index:: -fstack-check (gcc) 1329 1330:switch:`-fstack-check` 1331 Activates stack checking. 1332 See :ref:`Stack_Overflow_Checking` for details. 1333 1334 1335.. index:: -fstack-usage (gcc) 1336 1337:switch:`-fstack-usage` 1338 Makes the compiler output stack usage information for the program, on a 1339 per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details. 1340 1341 1342.. index:: -g (gcc) 1343 1344:switch:`-g` 1345 Generate debugging information. This information is stored in the object 1346 file and copied from there to the final executable file by the linker, 1347 where it can be read by the debugger. You must use the 1348 :switch:`-g` switch if you plan on using the debugger. 1349 1350 1351.. index:: -gnat05 (gcc) 1352 1353:switch:`-gnat05` 1354 Allow full Ada 2005 features. 1355 1356 1357.. index:: -gnat12 (gcc) 1358 1359:switch:`-gnat12` 1360 Allow full Ada 2012 features. 1361 1362.. index:: -gnat83 (gcc) 1363 1364.. index:: -gnat2005 (gcc) 1365 1366:switch:`-gnat2005` 1367 Allow full Ada 2005 features (same as :switch:`-gnat05`) 1368 1369 1370.. index:: -gnat2012 (gcc) 1371 1372:switch:`-gnat2012` 1373 Allow full Ada 2012 features (same as :switch:`-gnat12`) 1374 1375 1376:switch:`-gnat83` 1377 Enforce Ada 83 restrictions. 1378 1379 1380.. index:: -gnat95 (gcc) 1381 1382:switch:`-gnat95` 1383 Enforce Ada 95 restrictions. 1384 1385 Note: for compatibility with some Ada 95 compilers which support only 1386 the ``overriding`` keyword of Ada 2005, the :switch:`-gnatd.D` switch can 1387 be used along with :switch:`-gnat95` to achieve a similar effect with GNAT. 1388 1389 :switch:`-gnatd.D` instructs GNAT to consider ``overriding`` as a keyword 1390 and handle its associated semantic checks, even in Ada 95 mode. 1391 1392 1393.. index:: -gnata (gcc) 1394 1395:switch:`-gnata` 1396 Assertions enabled. ``Pragma Assert`` and ``pragma Debug`` to be 1397 activated. Note that these pragmas can also be controlled using the 1398 configuration pragmas ``Assertion_Policy`` and ``Debug_Policy``. 1399 It also activates pragmas ``Check``, ``Precondition``, and 1400 ``Postcondition``. Note that these pragmas can also be controlled 1401 using the configuration pragma ``Check_Policy``. In Ada 2012, it 1402 also activates all assertions defined in the RM as aspects: preconditions, 1403 postconditions, type invariants and (sub)type predicates. In all Ada modes, 1404 corresponding pragmas for type invariants and (sub)type predicates are 1405 also activated. The default is that all these assertions are disabled, 1406 and have no effect, other than being checked for syntactic validity, and 1407 in the case of subtype predicates, constructions such as membership tests 1408 still test predicates even if assertions are turned off. 1409 1410 1411.. index:: -gnatA (gcc) 1412 1413:switch:`-gnatA` 1414 Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present, 1415 it will be ignored. 1416 1417 1418.. index:: -gnatb (gcc) 1419 1420:switch:`-gnatb` 1421 Generate brief messages to :file:`stderr` even if verbose mode set. 1422 1423 1424.. index:: -gnatB (gcc) 1425 1426:switch:`-gnatB` 1427 Assume no invalid (bad) values except for 'Valid attribute use 1428 (:ref:`Validity_Checking`). 1429 1430 1431.. index:: -gnatc (gcc) 1432 1433:switch:`-gnatc` 1434 Check syntax and semantics only (no code generation attempted). When the 1435 compiler is invoked by ``gnatmake``, if the switch :switch:`-gnatc` is 1436 only given to the compiler (after :switch:`-cargs` or in package Compiler of 1437 the project file, ``gnatmake`` will fail because it will not find the 1438 object file after compilation. If ``gnatmake`` is called with 1439 :switch:`-gnatc` as a builder switch (before :switch:`-cargs` or in package 1440 Builder of the project file) then ``gnatmake`` will not fail because 1441 it will not look for the object files after compilation, and it will not try 1442 to build and link. 1443 1444 1445.. index:: -gnatC (gcc) 1446 1447:switch:`-gnatC` 1448 Generate CodePeer intermediate format (no code generation attempted). 1449 This switch will generate an intermediate representation suitable for 1450 use by CodePeer (:file:`.scil` files). This switch is not compatible with 1451 code generation (it will, among other things, disable some switches such 1452 as -gnatn, and enable others such as -gnata). 1453 1454 1455.. index:: -gnatd (gcc) 1456 1457:switch:`-gnatd` 1458 Specify debug options for the compiler. The string of characters after 1459 the :switch:`-gnatd` specify the specific debug options. The possible 1460 characters are 0-9, a-z, A-Z, optionally preceded by a dot. See 1461 compiler source file :file:`debug.adb` for details of the implemented 1462 debug options. Certain debug options are relevant to applications 1463 programmers, and these are documented at appropriate points in this 1464 users guide. 1465 1466 1467.. index:: -gnatD[nn] (gcc) 1468 1469:switch:`-gnatD` 1470 Create expanded source files for source level debugging. This switch 1471 also suppresses generation of cross-reference information 1472 (see :switch:`-gnatx`). Note that this switch is not allowed if a previous 1473 -gnatR switch has been given, since these two switches are not compatible. 1474 1475 1476.. index:: -gnateA (gcc) 1477 1478:switch:`-gnateA` 1479 Check that the actual parameters of a subprogram call are not aliases of one 1480 another. To qualify as aliasing, the actuals must denote objects of a composite 1481 type, their memory locations must be identical or overlapping, and at least one 1482 of the corresponding formal parameters must be of mode OUT or IN OUT. 1483 1484 1485 .. code-block:: ada 1486 1487 type Rec_Typ is record 1488 Data : Integer := 0; 1489 end record; 1490 1491 function Self (Val : Rec_Typ) return Rec_Typ is 1492 begin 1493 return Val; 1494 end Self; 1495 1496 procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is 1497 begin 1498 null; 1499 end Detect_Aliasing; 1500 1501 Obj : Rec_Typ; 1502 1503 Detect_Aliasing (Obj, Obj); 1504 Detect_Aliasing (Obj, Self (Obj)); 1505 1506 1507 In the example above, the first call to ``Detect_Aliasing`` fails with a 1508 ``Program_Error`` at runtime because the actuals for ``Val_1`` and 1509 ``Val_2`` denote the same object. The second call executes without raising 1510 an exception because ``Self(Obj)`` produces an anonymous object which does 1511 not share the memory location of ``Obj``. 1512 1513 1514.. index:: -gnatec (gcc) 1515 1516:switch:`-gnatec={path}` 1517 Specify a configuration pragma file 1518 (the equal sign is optional) 1519 (:ref:`The_Configuration_Pragmas_Files`). 1520 1521 1522.. index:: -gnateC (gcc) 1523 1524:switch:`-gnateC` 1525 Generate CodePeer messages in a compiler-like format. This switch is only 1526 effective if :switch:`-gnatcC` is also specified and requires an installation 1527 of CodePeer. 1528 1529 1530.. index:: -gnated (gcc) 1531 1532:switch:`-gnated` 1533 Disable atomic synchronization 1534 1535 1536.. index:: -gnateD (gcc) 1537 1538:switch:`-gnateDsymbol[={value}]` 1539 Defines a symbol, associated with ``value``, for preprocessing. 1540 (:ref:`Integrated_Preprocessing`). 1541 1542 1543.. index:: -gnateE (gcc) 1544 1545:switch:`-gnateE` 1546 Generate extra information in exception messages. In particular, display 1547 extra column information and the value and range associated with index and 1548 range check failures, and extra column information for access checks. 1549 In cases where the compiler is able to determine at compile time that 1550 a check will fail, it gives a warning, and the extra information is not 1551 produced at run time. 1552 1553 1554.. index:: -gnatef (gcc) 1555 1556:switch:`-gnatef` 1557 Display full source path name in brief error messages. 1558 1559 1560.. index:: -gnateF (gcc) 1561 1562:switch:`-gnateF` 1563 Check for overflow on all floating-point operations, including those 1564 for unconstrained predefined types. See description of pragma 1565 ``Check_Float_Overflow`` in GNAT RM. 1566 1567 1568.. index:: -gnateg (gcc) 1569 1570:switch:`-gnateg` 1571:switch:`-gnatceg` 1572 1573 The :switch:`-gnatc` switch must always be specified before this switch, e.g. 1574 :switch:`-gnatceg`. Generate a C header from the Ada input file. See 1575 :ref:`Generating_C_Headers_for_Ada_Specifications` for more 1576 information. 1577 1578 1579.. index:: -gnateG (gcc) 1580 1581:switch:`-gnateG` 1582 Save result of preprocessing in a text file. 1583 1584 1585.. index:: -gnatei (gcc) 1586 1587:switch:`-gnatei{nnn}` 1588 Set maximum number of instantiations during compilation of a single unit to 1589 ``nnn``. This may be useful in increasing the default maximum of 8000 for 1590 the rare case when a single unit legitimately exceeds this limit. 1591 1592 1593.. index:: -gnateI (gcc) 1594 1595:switch:`-gnateI{nnn}` 1596 Indicates that the source is a multi-unit source and that the index of the 1597 unit to compile is ``nnn``. ``nnn`` needs to be a positive number and need 1598 to be a valid index in the multi-unit source. 1599 1600 1601.. index:: -gnatel (gcc) 1602 1603:switch:`-gnatel` 1604 This switch can be used with the static elaboration model to issue info 1605 messages showing 1606 where implicit ``pragma Elaborate`` and ``pragma Elaborate_All`` 1607 are generated. This is useful in diagnosing elaboration circularities 1608 caused by these implicit pragmas when using the static elaboration 1609 model. See See the section in this guide on elaboration checking for 1610 further details. These messages are not generated by default, and are 1611 intended only for temporary use when debugging circularity problems. 1612 1613 1614.. index:: -gnatel (gcc) 1615 1616:switch:`-gnateL` 1617 This switch turns off the info messages about implicit elaboration pragmas. 1618 1619 1620.. index:: -gnatem (gcc) 1621 1622:switch:`-gnatem={path}` 1623 Specify a mapping file 1624 (the equal sign is optional) 1625 (:ref:`Units_to_Sources_Mapping_Files`). 1626 1627 1628.. index:: -gnatep (gcc) 1629 1630:switch:`-gnatep={file}` 1631 Specify a preprocessing data file 1632 (the equal sign is optional) 1633 (:ref:`Integrated_Preprocessing`). 1634 1635 1636.. index:: -gnateP (gcc) 1637 1638:switch:`-gnateP` 1639 Turn categorization dependency errors into warnings. 1640 Ada requires that units that WITH one another have compatible categories, for 1641 example a Pure unit cannot WITH a Preelaborate unit. If this switch is used, 1642 these errors become warnings (which can be ignored, or suppressed in the usual 1643 manner). This can be useful in some specialized circumstances such as the 1644 temporary use of special test software. 1645 1646 1647.. index:: -gnateS (gcc) 1648 1649:switch:`-gnateS` 1650 Synonym of :switch:`-fdump-scos`, kept for backwards compatibility. 1651 1652 1653.. index:: -gnatet=file (gcc) 1654 1655:switch:`-gnatet={path}` 1656 Generate target dependent information. The format of the output file is 1657 described in the section about switch :switch:`-gnateT`. 1658 1659 1660.. index:: -gnateT (gcc) 1661 1662:switch:`-gnateT={path}` 1663 Read target dependent information, such as endianness or sizes and alignments 1664 of base type. If this switch is passed, the default target dependent 1665 information of the compiler is replaced by the one read from the input file. 1666 This is used by tools other than the compiler, e.g. to do 1667 semantic analysis of programs that will run on some other target than 1668 the machine on which the tool is run. 1669 1670 The following target dependent values should be defined, 1671 where ``Nat`` denotes a natural integer value, ``Pos`` denotes a 1672 positive integer value, and fields marked with a question mark are 1673 boolean fields, where a value of 0 is False, and a value of 1 is True: 1674 1675 1676 :: 1677 1678 Bits_BE : Nat; -- Bits stored big-endian? 1679 Bits_Per_Unit : Pos; -- Bits in a storage unit 1680 Bits_Per_Word : Pos; -- Bits in a word 1681 Bytes_BE : Nat; -- Bytes stored big-endian? 1682 Char_Size : Pos; -- Standard.Character'Size 1683 Double_Float_Alignment : Nat; -- Alignment of double float 1684 Double_Scalar_Alignment : Nat; -- Alignment of double length scalar 1685 Double_Size : Pos; -- Standard.Long_Float'Size 1686 Float_Size : Pos; -- Standard.Float'Size 1687 Float_Words_BE : Nat; -- Float words stored big-endian? 1688 Int_Size : Pos; -- Standard.Integer'Size 1689 Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size 1690 Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size 1691 Long_Size : Pos; -- Standard.Long_Integer'Size 1692 Maximum_Alignment : Pos; -- Maximum permitted alignment 1693 Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field 1694 Pointer_Size : Pos; -- System.Address'Size 1695 Short_Enums : Nat; -- Short foreign convention enums? 1696 Short_Size : Pos; -- Standard.Short_Integer'Size 1697 Strict_Alignment : Nat; -- Strict alignment? 1698 System_Allocator_Alignment : Nat; -- Alignment for malloc calls 1699 Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size 1700 Words_BE : Nat; -- Words stored big-endian? 1701 1702 1703 The format of the input file is as follows. First come the values of 1704 the variables defined above, with one line per value: 1705 1706 1707 :: 1708 1709 name value 1710 1711 where ``name`` is the name of the parameter, spelled out in full, 1712 and cased as in the above list, and ``value`` is an unsigned decimal 1713 integer. Two or more blanks separates the name from the value. 1714 1715 All the variables must be present, in alphabetical order (i.e. the 1716 same order as the list above). 1717 1718 Then there is a blank line to separate the two parts of the file. Then 1719 come the lines showing the floating-point types to be registered, with 1720 one line per registered mode: 1721 1722 1723 :: 1724 1725 name digs float_rep size alignment 1726 1727 1728 where ``name`` is the string name of the type (which can have 1729 single spaces embedded in the name (e.g. long double), ``digs`` is 1730 the number of digits for the floating-point type, ``float_rep`` is 1731 the float representation (I/V/A for IEEE-754-Binary, Vax_Native, 1732 AAMP), ``size`` is the size in bits, ``alignment`` is the 1733 alignment in bits. The name is followed by at least two blanks, fields 1734 are separated by at least one blank, and a LF character immediately 1735 follows the alignment field. 1736 1737 Here is an example of a target parameterization file: 1738 1739 1740 :: 1741 1742 Bits_BE 0 1743 Bits_Per_Unit 8 1744 Bits_Per_Word 64 1745 Bytes_BE 0 1746 Char_Size 8 1747 Double_Float_Alignment 0 1748 Double_Scalar_Alignment 0 1749 Double_Size 64 1750 Float_Size 32 1751 Float_Words_BE 0 1752 Int_Size 64 1753 Long_Double_Size 128 1754 Long_Long_Size 64 1755 Long_Size 64 1756 Maximum_Alignment 16 1757 Max_Unaligned_Field 64 1758 Pointer_Size 64 1759 Short_Size 16 1760 Strict_Alignment 0 1761 System_Allocator_Alignment 16 1762 Wchar_T_Size 32 1763 Words_BE 0 1764 1765 float 15 I 64 64 1766 double 15 I 64 64 1767 long double 18 I 80 128 1768 TF 33 I 128 128 1769 1770 1771 1772.. index:: -gnateu (gcc) 1773 1774:switch:`-gnateu` 1775 Ignore unrecognized validity, warning, and style switches that 1776 appear after this switch is given. This may be useful when 1777 compiling sources developed on a later version of the compiler 1778 with an earlier version. Of course the earlier version must 1779 support this switch. 1780 1781 1782.. index:: -gnateV (gcc) 1783 1784:switch:`-gnateV` 1785 Check that all actual parameters of a subprogram call are valid according to 1786 the rules of validity checking (:ref:`Validity_Checking`). 1787 1788 1789.. index:: -gnateY (gcc) 1790 1791:switch:`-gnateY` 1792 Ignore all STYLE_CHECKS pragmas. Full legality checks 1793 are still carried out, but the pragmas have no effect 1794 on what style checks are active. This allows all style 1795 checking options to be controlled from the command line. 1796 1797 1798.. index:: -gnatE (gcc) 1799 1800:switch:`-gnatE` 1801 Full dynamic elaboration checks. 1802 1803 1804.. index:: -gnatf (gcc) 1805 1806:switch:`-gnatf` 1807 Full errors. Multiple errors per line, all undefined references, do not 1808 attempt to suppress cascaded errors. 1809 1810 1811.. index:: -gnatF (gcc) 1812 1813:switch:`-gnatF` 1814 Externals names are folded to all uppercase. 1815 1816 1817.. index:: -gnatg (gcc) 1818 1819:switch:`-gnatg` 1820 Internal GNAT implementation mode. This should not be used for 1821 applications programs, it is intended only for use by the compiler 1822 and its run-time library. For documentation, see the GNAT sources. 1823 Note that :switch:`-gnatg` implies 1824 :switch:`-gnatw.ge` and 1825 :switch:`-gnatyg` 1826 so that all standard warnings and all standard style options are turned on. 1827 All warnings and style messages are treated as errors. 1828 1829 1830.. index:: -gnatG[nn] (gcc) 1831 1832:switch:`-gnatG=nn` 1833 List generated expanded code in source form. 1834 1835 1836.. index:: -gnath (gcc) 1837 1838:switch:`-gnath` 1839 Output usage information. The output is written to :file:`stdout`. 1840 1841 1842.. index:: -gnati (gcc) 1843 1844:switch:`-gnati{c}` 1845 Identifier character set (``c`` = 1/2/3/4/8/9/p/f/n/w). 1846 For details of the possible selections for ``c``, 1847 see :ref:`Character_Set_Control`. 1848 1849 1850.. index:: -gnatI (gcc) 1851 1852:switch:`-gnatI` 1853 Ignore representation clauses. When this switch is used, 1854 representation clauses are treated as comments. This is useful 1855 when initially porting code where you want to ignore rep clause 1856 problems, and also for compiling foreign code (particularly 1857 for use with ASIS). The representation clauses that are ignored 1858 are: enumeration_representation_clause, record_representation_clause, 1859 and attribute_definition_clause for the following attributes: 1860 Address, Alignment, Bit_Order, Component_Size, Machine_Radix, 1861 Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size, 1862 and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored. 1863 Note that this option should be used only for compiling -- the 1864 code is likely to malfunction at run time. 1865 1866 Note that when :switch:`-gnatct` is used to generate trees for input 1867 into ASIS tools, these representation clauses are removed 1868 from the tree and ignored. This means that the tool will not see them. 1869 1870 1871.. index:: -gnatjnn (gcc) 1872 1873:switch:`-gnatj{nn}` 1874 Reformat error messages to fit on ``nn`` character lines 1875 1876 1877.. index:: -gnatk (gcc) 1878 1879:switch:`-gnatk={n}` 1880 Limit file names to ``n`` (1-999) characters (``k`` = krunch). 1881 1882 1883.. index:: -gnatl (gcc) 1884 1885:switch:`-gnatl` 1886 Output full source listing with embedded error messages. 1887 1888 1889.. index:: -gnatL (gcc) 1890 1891:switch:`-gnatL` 1892 Used in conjunction with -gnatG or -gnatD to intersperse original 1893 source lines (as comment lines with line numbers) in the expanded 1894 source output. 1895 1896 1897.. index:: -gnatm (gcc) 1898 1899:switch:`-gnatm={n}` 1900 Limit number of detected error or warning messages to ``n`` 1901 where ``n`` is in the range 1..999999. The default setting if 1902 no switch is given is 9999. If the number of warnings reaches this 1903 limit, then a message is output and further warnings are suppressed, 1904 but the compilation is continued. If the number of error messages 1905 reaches this limit, then a message is output and the compilation 1906 is abandoned. The equal sign here is optional. A value of zero 1907 means that no limit applies. 1908 1909 1910.. index:: -gnatn (gcc) 1911 1912:switch:`-gnatn[12]` 1913 Activate inlining across modules for subprograms for which pragma ``Inline`` 1914 is specified. This inlining is performed by the GCC back-end. An optional 1915 digit sets the inlining level: 1 for moderate inlining across modules 1916 or 2 for full inlining across modules. If no inlining level is specified, 1917 the compiler will pick it based on the optimization level. 1918 1919 1920.. index:: -gnatN (gcc) 1921 1922:switch:`-gnatN` 1923 Activate front end inlining for subprograms for which 1924 pragma ``Inline`` is specified. This inlining is performed 1925 by the front end and will be visible in the 1926 :switch:`-gnatG` output. 1927 1928 When using a gcc-based back end (in practice this means using any version 1929 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of 1930 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred. 1931 Historically front end inlining was more extensive than the gcc back end 1932 inlining, but that is no longer the case. 1933 1934 1935.. index:: -gnato0 (gcc) 1936 1937:switch:`-gnato0` 1938 Suppresses overflow checking. This causes the behavior of the compiler to 1939 match the default for older versions where overflow checking was suppressed 1940 by default. This is equivalent to having 1941 ``pragma Suppress (Overflow_Check)`` in a configuration pragma file. 1942 1943 1944.. index:: -gnato?? (gcc) 1945 1946:switch:`-gnato??` 1947 Set default mode for handling generation of code to avoid intermediate 1948 arithmetic overflow. Here ``??`` is two digits, a 1949 single digit, or nothing. Each digit is one of the digits ``1`` 1950 through ``3``: 1951 1952 ===== =============================================================== 1953 Digit Interpretation 1954 ----- --------------------------------------------------------------- 1955 *1* All intermediate overflows checked against base type (``STRICT``) 1956 *2* Minimize intermediate overflows (``MINIMIZED``) 1957 *3* Eliminate intermediate overflows (``ELIMINATED``) 1958 ===== =============================================================== 1959 1960 If only one digit appears, then it applies to all 1961 cases; if two digits are given, then the first applies outside 1962 assertions, pre/postconditions, and type invariants, and the second 1963 applies within assertions, pre/postconditions, and type invariants. 1964 1965 If no digits follow the :switch:`-gnato`, then it is equivalent to 1966 :switch:`-gnato11`, 1967 causing all intermediate overflows to be handled in strict 1968 mode. 1969 1970 This switch also causes arithmetic overflow checking to be performed 1971 (as though ``pragma Unsuppress (Overflow_Check)`` had been specified). 1972 1973 The default if no option :switch:`-gnato` is given is that overflow handling 1974 is in ``STRICT`` mode (computations done using the base type), and that 1975 overflow checking is enabled. 1976 1977 Note that division by zero is a separate check that is not 1978 controlled by this switch (divide-by-zero checking is on by default). 1979 1980 See also :ref:`Specifying_the_Desired_Mode`. 1981 1982 1983.. index:: -gnatp (gcc) 1984 1985:switch:`-gnatp` 1986 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch 1987 has no effect if cancelled by a subsequent :switch:`-gnat-p` switch. 1988 1989 1990.. index:: -gnat-p (gcc) 1991 1992:switch:`-gnat-p` 1993 Cancel effect of previous :switch:`-gnatp` switch. 1994 1995 1996.. index:: -gnatP (gcc) 1997 1998:switch:`-gnatP` 1999 Enable polling. This is required on some systems (notably Windows NT) to 2000 obtain asynchronous abort and asynchronous transfer of control capability. 2001 See ``Pragma_Polling`` in the :title:`GNAT_Reference_Manual` for full 2002 details. 2003 2004 2005.. index:: -gnatq (gcc) 2006 2007:switch:`-gnatq` 2008 Don't quit. Try semantics, even if parse errors. 2009 2010 2011.. index:: -gnatQ (gcc) 2012 2013:switch:`-gnatQ` 2014 Don't quit. Generate :file:`ALI` and tree files even if illegalities. 2015 Note that code generation is still suppressed in the presence of any 2016 errors, so even with :switch:`-gnatQ` no object file is generated. 2017 2018 2019.. index:: -gnatr (gcc) 2020 2021:switch:`-gnatr` 2022 Treat pragma Restrictions as Restriction_Warnings. 2023 2024 2025.. index:: -gnatR (gcc) 2026 2027:switch:`-gnatR[0/1/2/3][e][m][s]` 2028 Output representation information for declared types, objects and 2029 subprograms. Note that this switch is not allowed if a previous 2030 :switch:`-gnatD` switch has been given, since these two switches 2031 are not compatible. 2032 2033 2034.. index:: -gnats (gcc) 2035 2036:switch:`-gnats` 2037 Syntax check only. 2038 2039 2040.. index:: -gnatS (gcc) 2041 2042:switch:`-gnatS` 2043 Print package Standard. 2044 2045 2046.. index:: -gnatt (gcc) 2047 2048:switch:`-gnatt` 2049 Generate tree output file. 2050 2051 2052.. index:: -gnatT (gcc) 2053 2054:switch:`-gnatT{nnn}` 2055 All compiler tables start at ``nnn`` times usual starting size. 2056 2057 2058.. index:: -gnatu (gcc) 2059 2060:switch:`-gnatu` 2061 List units for this compilation. 2062 2063 2064.. index:: -gnatU (gcc) 2065 2066:switch:`-gnatU` 2067 Tag all error messages with the unique string 'error:' 2068 2069 2070.. index:: -gnatv (gcc) 2071 2072:switch:`-gnatv` 2073 Verbose mode. Full error output with source lines to :file:`stdout`. 2074 2075 2076.. index:: -gnatV (gcc) 2077 2078:switch:`-gnatV` 2079 Control level of validity checking (:ref:`Validity_Checking`). 2080 2081 2082.. index:: -gnatw (gcc) 2083 2084:switch:`-gnatw{xxx}` 2085 Warning mode where 2086 ``xxx`` is a string of option letters that denotes 2087 the exact warnings that 2088 are enabled or disabled (:ref:`Warning_Message_Control`). 2089 2090 2091.. index:: -gnatW (gcc) 2092 2093:switch:`-gnatW{e}` 2094 Wide character encoding method 2095 (``e``\ =n/h/u/s/e/8). 2096 2097 2098.. index:: -gnatx (gcc) 2099 2100:switch:`-gnatx` 2101 Suppress generation of cross-reference information. 2102 2103 2104.. index:: -gnatX (gcc) 2105 2106:switch:`-gnatX` 2107 Enable GNAT implementation extensions and latest Ada version. 2108 2109 2110.. index:: -gnaty (gcc) 2111 2112:switch:`-gnaty` 2113 Enable built-in style checks (:ref:`Style_Checking`). 2114 2115 2116.. index:: -gnatz (gcc) 2117 2118:switch:`-gnatz{m}` 2119 Distribution stub generation and compilation 2120 (``m``\ =r/c for receiver/caller stubs). 2121 2122 2123.. index:: -I (gcc) 2124 2125:switch:`-I{dir}` 2126 .. index:: RTL 2127 2128 Direct GNAT to search the ``dir`` directory for source files needed by 2129 the current compilation 2130 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). 2131 2132 2133.. index:: -I- (gcc) 2134 2135:switch:`-I-` 2136 .. index:: RTL 2137 2138 Except for the source file named in the command line, do not look for source 2139 files in the directory containing the source file named in the command line 2140 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). 2141 2142 2143.. index:: -o (gcc) 2144 2145:switch:`-o {file}` 2146 This switch is used in ``gcc`` to redirect the generated object file 2147 and its associated ALI file. Beware of this switch with GNAT, because it may 2148 cause the object file and ALI file to have different names which in turn 2149 may confuse the binder and the linker. 2150 2151 2152.. index:: -nostdinc (gcc) 2153 2154:switch:`-nostdinc` 2155 Inhibit the search of the default location for the GNAT Run Time 2156 Library (RTL) source files. 2157 2158 2159.. index:: -nostdlib (gcc) 2160 2161:switch:`-nostdlib` 2162 Inhibit the search of the default location for the GNAT Run Time 2163 Library (RTL) ALI files. 2164 2165 2166.. index:: -O (gcc) 2167 2168:switch:`-O[{n}]` 2169 ``n`` controls the optimization level: 2170 2171 ======= ================================================================== 2172 *n* Effect 2173 ------- ------------------------------------------------------------------ 2174 *0* No optimization, the default setting if no :switch:`-O` appears 2175 *1* Normal optimization, the default if you specify :switch:`-O` without an 2176 operand. A good compromise between code quality and compilation 2177 time. 2178 *2* Extensive optimization, may improve execution time, possibly at 2179 the cost of substantially increased compilation time. 2180 *3* Same as :switch:`-O2`, and also includes inline expansion for small 2181 subprograms in the same unit. 2182 *s* Optimize space usage 2183 ======= ================================================================== 2184 2185 See also :ref:`Optimization_Levels`. 2186 2187 2188.. index:: -pass-exit-codes (gcc) 2189 2190:switch:`-pass-exit-codes` 2191 Catch exit codes from the compiler and use the most meaningful as 2192 exit status. 2193 2194 2195.. index:: --RTS (gcc) 2196 2197:switch:`--RTS={rts-path}` 2198 Specifies the default location of the runtime library. Same meaning as the 2199 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). 2200 2201 2202.. index:: -S (gcc) 2203 2204:switch:`-S` 2205 Used in place of :switch:`-c` to 2206 cause the assembler source file to be 2207 generated, using :file:`.s` as the extension, 2208 instead of the object file. 2209 This may be useful if you need to examine the generated assembly code. 2210 2211 2212.. index:: -fverbose-asm (gcc) 2213 2214:switch:`-fverbose-asm` 2215 Used in conjunction with :switch:`-S` 2216 to cause the generated assembly code file to be annotated with variable 2217 names, making it significantly easier to follow. 2218 2219 2220.. index:: -v (gcc) 2221 2222:switch:`-v` 2223 Show commands generated by the ``gcc`` driver. Normally used only for 2224 debugging purposes or if you need to be sure what version of the 2225 compiler you are executing. 2226 2227 2228.. index:: -V (gcc) 2229 2230:switch:`-V {ver}` 2231 Execute ``ver`` version of the compiler. This is the ``gcc`` 2232 version, not the GNAT version. 2233 2234 2235.. index:: -w (gcc) 2236 2237:switch:`-w` 2238 Turn off warnings generated by the back end of the compiler. Use of 2239 this switch also causes the default for front end warnings to be set 2240 to suppress (as though :switch:`-gnatws` had appeared at the start of 2241 the options). 2242 2243 2244.. index:: Combining GNAT switches 2245 2246You may combine a sequence of GNAT switches into a single switch. For 2247example, the combined switch 2248 2249 :: 2250 2251 -gnatofi3 2252 2253is equivalent to specifying the following sequence of switches: 2254 2255 :: 2256 2257 -gnato -gnatf -gnati3 2258 2259The following restrictions apply to the combination of switches 2260in this manner: 2261 2262* The switch :switch:`-gnatc` if combined with other switches must come 2263 first in the string. 2264 2265* The switch :switch:`-gnats` if combined with other switches must come 2266 first in the string. 2267 2268* The switches 2269 :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other 2270 switches, and only one of them may appear in the command line. 2271 2272* The switch :switch:`-gnat-p` may not be combined with any other switch. 2273 2274* Once a 'y' appears in the string (that is a use of the :switch:`-gnaty` 2275 switch), then all further characters in the switch are interpreted 2276 as style modifiers (see description of :switch:`-gnaty`). 2277 2278* Once a 'd' appears in the string (that is a use of the :switch:`-gnatd` 2279 switch), then all further characters in the switch are interpreted 2280 as debug flags (see description of :switch:`-gnatd`). 2281 2282* Once a 'w' appears in the string (that is a use of the :switch:`-gnatw` 2283 switch), then all further characters in the switch are interpreted 2284 as warning mode modifiers (see description of :switch:`-gnatw`). 2285 2286* Once a 'V' appears in the string (that is a use of the :switch:`-gnatV` 2287 switch), then all further characters in the switch are interpreted 2288 as validity checking options (:ref:`Validity_Checking`). 2289 2290* Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in 2291 a combined list of options. 2292 2293.. _Output_and_Error_Message_Control: 2294 2295Output and Error Message Control 2296-------------------------------- 2297 2298.. index:: stderr 2299 2300The standard default format for error messages is called 'brief format'. 2301Brief format messages are written to :file:`stderr` (the standard error 2302file) and have the following form: 2303 2304:: 2305 2306 e.adb:3:04: Incorrect spelling of keyword "function" 2307 e.adb:4:20: ";" should be "is" 2308 2309The first integer after the file name is the line number in the file, 2310and the second integer is the column number within the line. 2311``GPS`` can parse the error messages 2312and point to the referenced character. 2313The following switches provide control over the error message 2314format: 2315 2316 2317.. index:: -gnatv (gcc) 2318 2319:switch:`-gnatv` 2320 The ``v`` stands for verbose. 2321 The effect of this setting is to write long-format error 2322 messages to :file:`stdout` (the standard output file. 2323 The same program compiled with the 2324 :switch:`-gnatv` switch would generate: 2325 2326 :: 2327 2328 3. funcion X (Q : Integer) 2329 | 2330 >>> Incorrect spelling of keyword "function" 2331 4. return Integer; 2332 | 2333 >>> ";" should be "is" 2334 2335 2336 The vertical bar indicates the location of the error, and the ``>>>`` 2337 prefix can be used to search for error messages. When this switch is 2338 used the only source lines output are those with errors. 2339 2340 2341.. index:: -gnatl (gcc) 2342 2343:switch:`-gnatl` 2344 The ``l`` stands for list. 2345 This switch causes a full listing of 2346 the file to be generated. In the case where a body is 2347 compiled, the corresponding spec is also listed, along 2348 with any subunits. Typical output from compiling a package 2349 body :file:`p.adb` might look like:: 2350 2351 Compiling: p.adb 2352 2353 1. package body p is 2354 2. procedure a; 2355 3. procedure a is separate; 2356 4. begin 2357 5. null 2358 | 2359 >>> missing ";" 2360 2361 6. end; 2362 2363 Compiling: p.ads 2364 2365 1. package p is 2366 2. pragma Elaborate_Body 2367 | 2368 >>> missing ";" 2369 2370 3. end p; 2371 2372 Compiling: p-a.adb 2373 2374 1. separate p 2375 | 2376 >>> missing "(" 2377 2378 2. procedure a is 2379 3. begin 2380 4. null 2381 | 2382 >>> missing ";" 2383 2384 5. end; 2385 2386 2387 When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and 2388 standard output is redirected, a brief summary is written to 2389 :file:`stderr` (standard error) giving the number of error messages and 2390 warning messages generated. 2391 2392 2393.. index:: -gnatl=fname (gcc) 2394 2395:switch:`-gnatl={fname}` 2396 This has the same effect as :switch:`-gnatl` except that the output is 2397 written to a file instead of to standard output. If the given name 2398 :file:`fname` does not start with a period, then it is the full name 2399 of the file to be written. If :file:`fname` is an extension, it is 2400 appended to the name of the file being compiled. For example, if 2401 file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`, 2402 then the output is written to file xyz.adb.lst. 2403 2404 2405.. index:: -gnatU (gcc) 2406 2407:switch:`-gnatU` 2408 This switch forces all error messages to be preceded by the unique 2409 string 'error:'. This means that error messages take a few more 2410 characters in space, but allows easy searching for and identification 2411 of error messages. 2412 2413 2414.. index:: -gnatb (gcc) 2415 2416:switch:`-gnatb` 2417 The ``b`` stands for brief. 2418 This switch causes GNAT to generate the 2419 brief format error messages to :file:`stderr` (the standard error 2420 file) as well as the verbose 2421 format message or full listing (which as usual is written to 2422 :file:`stdout` (the standard output file). 2423 2424 2425.. index:: -gnatm (gcc) 2426 2427:switch:`-gnatm={n}` 2428 The ``m`` stands for maximum. 2429 ``n`` is a decimal integer in the 2430 range of 1 to 999999 and limits the number of error or warning 2431 messages to be generated. For example, using 2432 :switch:`-gnatm2` might yield 2433 2434 :: 2435 2436 e.adb:3:04: Incorrect spelling of keyword "function" 2437 e.adb:5:35: missing ".." 2438 fatal error: maximum number of errors detected 2439 compilation abandoned 2440 2441 2442 The default setting if 2443 no switch is given is 9999. If the number of warnings reaches this 2444 limit, then a message is output and further warnings are suppressed, 2445 but the compilation is continued. If the number of error messages 2446 reaches this limit, then a message is output and the compilation 2447 is abandoned. A value of zero means that no limit applies. 2448 2449 Note that the equal sign is optional, so the switches 2450 :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent. 2451 2452 2453.. index:: -gnatf (gcc) 2454 2455:switch:`-gnatf` 2456 .. index:: Error messages, suppressing 2457 2458 The ``f`` stands for full. 2459 Normally, the compiler suppresses error messages that are likely to be 2460 redundant. This switch causes all error 2461 messages to be generated. In particular, in the case of 2462 references to undefined variables. If a given variable is referenced 2463 several times, the normal format of messages is 2464 2465 :: 2466 2467 e.adb:7:07: "V" is undefined (more references follow) 2468 2469 where the parenthetical comment warns that there are additional 2470 references to the variable ``V``. Compiling the same program with the 2471 :switch:`-gnatf` switch yields 2472 2473 :: 2474 2475 e.adb:7:07: "V" is undefined 2476 e.adb:8:07: "V" is undefined 2477 e.adb:8:12: "V" is undefined 2478 e.adb:8:16: "V" is undefined 2479 e.adb:9:07: "V" is undefined 2480 e.adb:9:12: "V" is undefined 2481 2482 The :switch:`-gnatf` switch also generates additional information for 2483 some error messages. Some examples are: 2484 2485 * Details on possibly non-portable unchecked conversion 2486 2487 * List possible interpretations for ambiguous calls 2488 2489 * Additional details on incorrect parameters 2490 2491 2492.. index:: -gnatjnn (gcc) 2493 2494:switch:`-gnatjnn` 2495 In normal operation mode (or if :switch:`-gnatj0` is used), then error messages 2496 with continuation lines are treated as though the continuation lines were 2497 separate messages (and so a warning with two continuation lines counts as 2498 three warnings, and is listed as three separate messages). 2499 2500 If the :switch:`-gnatjnn` switch is used with a positive value for nn, then 2501 messages are output in a different manner. A message and all its continuation 2502 lines are treated as a unit, and count as only one warning or message in the 2503 statistics totals. Furthermore, the message is reformatted so that no line 2504 is longer than nn characters. 2505 2506 2507.. index:: -gnatq (gcc) 2508 2509:switch:`-gnatq` 2510 The ``q`` stands for quit (really 'don't quit'). 2511 In normal operation mode, the compiler first parses the program and 2512 determines if there are any syntax errors. If there are, appropriate 2513 error messages are generated and compilation is immediately terminated. 2514 This switch tells 2515 GNAT to continue with semantic analysis even if syntax errors have been 2516 found. This may enable the detection of more errors in a single run. On 2517 the other hand, the semantic analyzer is more likely to encounter some 2518 internal fatal error when given a syntactically invalid tree. 2519 2520 2521.. index:: -gnatQ (gcc) 2522 2523:switch:`-gnatQ` 2524 In normal operation mode, the :file:`ALI` file is not generated if any 2525 illegalities are detected in the program. The use of :switch:`-gnatQ` forces 2526 generation of the :file:`ALI` file. This file is marked as being in 2527 error, so it cannot be used for binding purposes, but it does contain 2528 reasonably complete cross-reference information, and thus may be useful 2529 for use by tools (e.g., semantic browsing tools or integrated development 2530 environments) that are driven from the :file:`ALI` file. This switch 2531 implies :switch:`-gnatq`, since the semantic phase must be run to get a 2532 meaningful ALI file. 2533 2534 In addition, if :switch:`-gnatt` is also specified, then the tree file is 2535 generated even if there are illegalities. It may be useful in this case 2536 to also specify :switch:`-gnatq` to ensure that full semantic processing 2537 occurs. The resulting tree file can be processed by ASIS, for the purpose 2538 of providing partial information about illegal units, but if the error 2539 causes the tree to be badly malformed, then ASIS may crash during the 2540 analysis. 2541 2542 When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as 2543 being in error, ``gnatmake`` will attempt to recompile the source when it 2544 finds such an :file:`ALI` file, including with switch :switch:`-gnatc`. 2545 2546 Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified, 2547 since ALI files are never generated if :switch:`-gnats` is set. 2548 2549 2550.. _Warning_Message_Control: 2551 2552Warning Message Control 2553----------------------- 2554 2555.. index:: Warning messages 2556 2557In addition to error messages, which correspond to illegalities as defined 2558in the Ada Reference Manual, the compiler detects two kinds of warning 2559situations. 2560 2561First, the compiler considers some constructs suspicious and generates a 2562warning message to alert you to a possible error. Second, if the 2563compiler detects a situation that is sure to raise an exception at 2564run time, it generates a warning message. The following shows an example 2565of warning messages: 2566 2567:: 2568 2569 e.adb:4:24: warning: creation of object may raise Storage_Error 2570 e.adb:10:17: warning: static value out of range 2571 e.adb:10:17: warning: "Constraint_Error" will be raised at run time 2572 2573 2574GNAT considers a large number of situations as appropriate 2575for the generation of warning messages. As always, warnings are not 2576definite indications of errors. For example, if you do an out-of-range 2577assignment with the deliberate intention of raising a 2578``Constraint_Error`` exception, then the warning that may be 2579issued does not indicate an error. Some of the situations for which GNAT 2580issues warnings (at least some of the time) are given in the following 2581list. This list is not complete, and new warnings are often added to 2582subsequent versions of GNAT. The list is intended to give a general idea 2583of the kinds of warnings that are generated. 2584 2585* Possible infinitely recursive calls 2586 2587* Out-of-range values being assigned 2588 2589* Possible order of elaboration problems 2590 2591* Size not a multiple of alignment for a record type 2592 2593* Assertions (pragma Assert) that are sure to fail 2594 2595* Unreachable code 2596 2597* Address clauses with possibly unaligned values, or where an attempt is 2598 made to overlay a smaller variable with a larger one. 2599 2600* Fixed-point type declarations with a null range 2601 2602* Direct_IO or Sequential_IO instantiated with a type that has access values 2603 2604* Variables that are never assigned a value 2605 2606* Variables that are referenced before being initialized 2607 2608* Task entries with no corresponding ``accept`` statement 2609 2610* Duplicate accepts for the same task entry in a ``select`` 2611 2612* Objects that take too much storage 2613 2614* Unchecked conversion between types of differing sizes 2615 2616* Missing ``return`` statement along some execution path in a function 2617 2618* Incorrect (unrecognized) pragmas 2619 2620* Incorrect external names 2621 2622* Allocation from empty storage pool 2623 2624* Potentially blocking operation in protected type 2625 2626* Suspicious parenthesization of expressions 2627 2628* Mismatching bounds in an aggregate 2629 2630* Attempt to return local value by reference 2631 2632* Premature instantiation of a generic body 2633 2634* Attempt to pack aliased components 2635 2636* Out of bounds array subscripts 2637 2638* Wrong length on string assignment 2639 2640* Violations of style rules if style checking is enabled 2641 2642* Unused |with| clauses 2643 2644* ``Bit_Order`` usage that does not have any effect 2645 2646* ``Standard.Duration`` used to resolve universal fixed expression 2647 2648* Dereference of possibly null value 2649 2650* Declaration that is likely to cause storage error 2651 2652* Internal GNAT unit |withed| by application unit 2653 2654* Values known to be out of range at compile time 2655 2656* Unreferenced or unmodified variables. Note that a special 2657 exemption applies to variables which contain any of the substrings 2658 ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables 2659 are considered likely to be intentionally used in a situation where 2660 otherwise a warning would be given, so warnings of this kind are 2661 always suppressed for such variables. 2662 2663* Address overlays that could clobber memory 2664 2665* Unexpected initialization when address clause present 2666 2667* Bad alignment for address clause 2668 2669* Useless type conversions 2670 2671* Redundant assignment statements and other redundant constructs 2672 2673* Useless exception handlers 2674 2675* Accidental hiding of name by child unit 2676 2677* Access before elaboration detected at compile time 2678 2679* A range in a ``for`` loop that is known to be null or might be null 2680 2681 2682The following section lists compiler switches that are available 2683to control the handling of warning messages. It is also possible 2684to exercise much finer control over what warnings are issued and 2685suppressed using the GNAT pragma Warnings (see the description 2686of the pragma in the :title:`GNAT_Reference_manual`). 2687 2688 2689.. index:: -gnatwa (gcc) 2690 2691:switch:`-gnatwa` 2692 *Activate most optional warnings.* 2693 2694 This switch activates most optional warning messages. See the remaining list 2695 in this section for details on optional warning messages that can be 2696 individually controlled. The warnings that are not turned on by this 2697 switch are: 2698 2699 2700 * :switch:`-gnatwd` (implicit dereferencing) 2701 2702 * :switch:`-gnatw.d` (tag warnings with -gnatw switch) 2703 2704 * :switch:`-gnatwh` (hiding) 2705 2706 * :switch:`-gnatw.h` (holes in record layouts) 2707 2708 * :switch:`-gnatw.j` (late primitives of tagged types) 2709 2710 * :switch:`-gnatw.k` (redefinition of names in standard) 2711 2712 * :switch:`-gnatwl` (elaboration warnings) 2713 2714 * :switch:`-gnatw.l` (inherited aspects) 2715 2716 * :switch:`-gnatw.n` (atomic synchronization) 2717 2718 * :switch:`-gnatwo` (address clause overlay) 2719 2720 * :switch:`-gnatw.o` (values set by out parameters ignored) 2721 2722 * :switch:`-gnatw.q` (questionable layout of record types) 2723 2724 * :switch:`-gnatw.s` (overridden size clause) 2725 2726 * :switch:`-gnatwt` (tracking of deleted conditional code) 2727 2728 * :switch:`-gnatw.u` (unordered enumeration) 2729 2730 * :switch:`-gnatw.w` (use of Warnings Off) 2731 2732 * :switch:`-gnatw.y` (reasons for package needing body) 2733 2734 All other optional warnings are turned on. 2735 2736 2737.. index:: -gnatwA (gcc) 2738 2739:switch:`-gnatwA` 2740 *Suppress all optional errors.* 2741 2742 This switch suppresses all optional warning messages, see remaining list 2743 in this section for details on optional warning messages that can be 2744 individually controlled. Note that unlike switch :switch:`-gnatws`, the 2745 use of switch :switch:`-gnatwA` does not suppress warnings that are 2746 normally given unconditionally and cannot be individually controlled 2747 (for example, the warning about a missing exit path in a function). 2748 Also, again unlike switch :switch:`-gnatws`, warnings suppressed by 2749 the use of switch :switch:`-gnatwA` can be individually turned back 2750 on. For example the use of switch :switch:`-gnatwA` followed by 2751 switch :switch:`-gnatwd` will suppress all optional warnings except 2752 the warnings for implicit dereferencing. 2753 2754.. index:: -gnatw.a (gcc) 2755 2756:switch:`-gnatw.a` 2757 *Activate warnings on failing assertions.* 2758 2759 .. index:: Assert failures 2760 2761 This switch activates warnings for assertions where the compiler can tell at 2762 compile time that the assertion will fail. Note that this warning is given 2763 even if assertions are disabled. The default is that such warnings are 2764 generated. 2765 2766 2767.. index:: -gnatw.A (gcc) 2768 2769:switch:`-gnatw.A` 2770 *Suppress warnings on failing assertions.* 2771 2772 .. index:: Assert failures 2773 2774 This switch suppresses warnings for assertions where the compiler can tell at 2775 compile time that the assertion will fail. 2776 2777 2778.. index:: -gnatwb (gcc) 2779 2780:switch:`-gnatwb` 2781 *Activate warnings on bad fixed values.* 2782 2783 .. index:: Bad fixed values 2784 2785 .. index:: Fixed-point Small value 2786 2787 .. index:: Small value 2788 2789 This switch activates warnings for static fixed-point expressions whose 2790 value is not an exact multiple of Small. Such values are implementation 2791 dependent, since an implementation is free to choose either of the multiples 2792 that surround the value. GNAT always chooses the closer one, but this is not 2793 required behavior, and it is better to specify a value that is an exact 2794 multiple, ensuring predictable execution. The default is that such warnings 2795 are not generated. 2796 2797 2798.. index:: -gnatwB (gcc) 2799 2800:switch:`-gnatwB` 2801 *Suppress warnings on bad fixed values.* 2802 2803 This switch suppresses warnings for static fixed-point expressions whose 2804 value is not an exact multiple of Small. 2805 2806 2807.. index:: -gnatw.b (gcc) 2808 2809:switch:`-gnatw.b` 2810 *Activate warnings on biased representation.* 2811 2812 .. index:: Biased representation 2813 2814 This switch activates warnings when a size clause, value size clause, component 2815 clause, or component size clause forces the use of biased representation for an 2816 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 2817 to represent 10/11). The default is that such warnings are generated. 2818 2819 2820.. index:: -gnatwB (gcc) 2821 2822:switch:`-gnatw.B` 2823 *Suppress warnings on biased representation.* 2824 2825 This switch suppresses warnings for representation clauses that force the use 2826 of biased representation. 2827 2828 2829.. index:: -gnatwc (gcc) 2830 2831:switch:`-gnatwc` 2832 *Activate warnings on conditionals.* 2833 2834 .. index:: Conditionals, constant 2835 2836 This switch activates warnings for conditional expressions used in 2837 tests that are known to be True or False at compile time. The default 2838 is that such warnings are not generated. 2839 Note that this warning does 2840 not get issued for the use of boolean variables or constants whose 2841 values are known at compile time, since this is a standard technique 2842 for conditional compilation in Ada, and this would generate too many 2843 false positive warnings. 2844 2845 This warning option also activates a special test for comparisons using 2846 the operators '>=' and' <='. 2847 If the compiler can tell that only the equality condition is possible, 2848 then it will warn that the '>' or '<' part of the test 2849 is useless and that the operator could be replaced by '='. 2850 An example would be comparing a ``Natural`` variable <= 0. 2851 2852 This warning option also generates warnings if 2853 one or both tests is optimized away in a membership test for integer 2854 values if the result can be determined at compile time. Range tests on 2855 enumeration types are not included, since it is common for such tests 2856 to include an end point. 2857 2858 This warning can also be turned on using :switch:`-gnatwa`. 2859 2860 2861.. index:: -gnatwC (gcc) 2862 2863:switch:`-gnatwC` 2864 *Suppress warnings on conditionals.* 2865 2866 This switch suppresses warnings for conditional expressions used in 2867 tests that are known to be True or False at compile time. 2868 2869 2870.. index:: -gnatw.c (gcc) 2871 2872:switch:`-gnatw.c` 2873 *Activate warnings on missing component clauses.* 2874 2875 .. index:: Component clause, missing 2876 2877 This switch activates warnings for record components where a record 2878 representation clause is present and has component clauses for the 2879 majority, but not all, of the components. A warning is given for each 2880 component for which no component clause is present. 2881 2882 2883.. index:: -gnatwC (gcc) 2884 2885:switch:`-gnatw.C` 2886 *Suppress warnings on missing component clauses.* 2887 2888 This switch suppresses warnings for record components that are 2889 missing a component clause in the situation described above. 2890 2891 2892.. index:: -gnatwd (gcc) 2893 2894:switch:`-gnatwd` 2895 *Activate warnings on implicit dereferencing.* 2896 2897 If this switch is set, then the use of a prefix of an access type 2898 in an indexed component, slice, or selected component without an 2899 explicit ``.all`` will generate a warning. With this warning 2900 enabled, access checks occur only at points where an explicit 2901 ``.all`` appears in the source code (assuming no warnings are 2902 generated as a result of this switch). The default is that such 2903 warnings are not generated. 2904 2905 2906.. index:: -gnatwD (gcc) 2907 2908:switch:`-gnatwD` 2909 *Suppress warnings on implicit dereferencing.* 2910 2911 .. index:: Implicit dereferencing 2912 2913 .. index:: Dereferencing, implicit 2914 2915 This switch suppresses warnings for implicit dereferences in 2916 indexed components, slices, and selected components. 2917 2918 2919.. index:: -gnatw.d (gcc) 2920 2921:switch:`-gnatw.d` 2922 *Activate tagging of warning and info messages.* 2923 2924 If this switch is set, then warning messages are tagged, with one of the 2925 following strings: 2926 2927 - *[-gnatw?]* 2928 Used to tag warnings controlled by the switch :switch:`-gnatwx` where x 2929 is a letter a-z. 2930 2931 2932 - *[-gnatw.?]* 2933 Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x 2934 is a letter a-z. 2935 2936 2937 - *[-gnatel]* 2938 Used to tag elaboration information (info) messages generated when the 2939 static model of elaboration is used and the :switch:`-gnatel` switch is set. 2940 2941 2942 - *[restriction warning]* 2943 Used to tag warning messages for restriction violations, activated by use 2944 of the pragma ``Restriction_Warnings``. 2945 2946 2947 - *[warning-as-error]* 2948 Used to tag warning messages that have been converted to error messages by 2949 use of the pragma Warning_As_Error. Note that such warnings are prefixed by 2950 the string "error: " rather than "warning: ". 2951 2952 2953 - *[enabled by default]* 2954 Used to tag all other warnings that are always given by default, unless 2955 warnings are completely suppressed using pragma *Warnings(Off)* or 2956 the switch :switch:`-gnatws`. 2957 2958 2959 2960.. index:: -gnatw.d (gcc) 2961 2962:switch:`-gnatw.D` 2963 *Deactivate tagging of warning and info messages messages.* 2964 2965 If this switch is set, then warning messages return to the default 2966 mode in which warnings and info messages are not tagged as described above for 2967 :switch:`-gnatw.d`. 2968 2969 2970.. index:: -gnatwe (gcc) 2971.. index:: Warnings, treat as error 2972 2973:switch:`-gnatwe` 2974 *Treat warnings and style checks as errors.* 2975 2976 This switch causes warning messages and style check messages to be 2977 treated as errors. 2978 The warning string still appears, but the warning messages are counted 2979 as errors, and prevent the generation of an object file. Note that this 2980 is the only -gnatw switch that affects the handling of style check messages. 2981 Note also that this switch has no effect on info (information) messages, which 2982 are not treated as errors if this switch is present. 2983 2984 2985.. index:: -gnatw.e (gcc) 2986 2987:switch:`-gnatw.e` 2988 *Activate every optional warning.* 2989 2990 .. index:: Warnings, activate every optional warning 2991 2992 This switch activates all optional warnings, including those which 2993 are not activated by :switch:`-gnatwa`. The use of this switch is not 2994 recommended for normal use. If you turn this switch on, it is almost 2995 certain that you will get large numbers of useless warnings. The 2996 warnings that are excluded from :switch:`-gnatwa` are typically highly 2997 specialized warnings that are suitable for use only in code that has 2998 been specifically designed according to specialized coding rules. 2999 3000 3001.. index:: -gnatwE (gcc) 3002.. index:: Warnings, treat as error 3003 3004:switch:`-gnatwE` 3005 *Treat all run-time exception warnings as errors.* 3006 3007 This switch causes warning messages regarding errors that will be raised 3008 during run-time execution to be treated as errors. 3009 3010 3011.. index:: -gnatwf (gcc) 3012 3013:switch:`-gnatwf` 3014 *Activate warnings on unreferenced formals.* 3015 3016 .. index:: Formals, unreferenced 3017 3018 This switch causes a warning to be generated if a formal parameter 3019 is not referenced in the body of the subprogram. This warning can 3020 also be turned on using :switch:`-gnatwu`. The 3021 default is that these warnings are not generated. 3022 3023 3024.. index:: -gnatwF (gcc) 3025 3026:switch:`-gnatwF` 3027 *Suppress warnings on unreferenced formals.* 3028 3029 This switch suppresses warnings for unreferenced formal 3030 parameters. Note that the 3031 combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the 3032 effect of warning on unreferenced entities other than subprogram 3033 formals. 3034 3035 3036.. index:: -gnatwg (gcc) 3037 3038:switch:`-gnatwg` 3039 *Activate warnings on unrecognized pragmas.* 3040 3041 .. index:: Pragmas, unrecognized 3042 3043 This switch causes a warning to be generated if an unrecognized 3044 pragma is encountered. Apart from issuing this warning, the 3045 pragma is ignored and has no effect. The default 3046 is that such warnings are issued (satisfying the Ada Reference 3047 Manual requirement that such warnings appear). 3048 3049 3050.. index:: -gnatwG (gcc) 3051 3052:switch:`-gnatwG` 3053 *Suppress warnings on unrecognized pragmas.* 3054 3055 This switch suppresses warnings for unrecognized pragmas. 3056 3057 3058.. index:: -gnatw.g (gcc) 3059 3060:switch:`-gnatw.g` 3061 *Warnings used for GNAT sources.* 3062 3063 This switch sets the warning categories that are used by the standard 3064 GNAT style. Currently this is equivalent to 3065 :switch:`-gnatwAao.q.s.CI.V.X.Z` 3066 but more warnings may be added in the future without advanced notice. 3067 3068 3069.. index:: -gnatwh (gcc) 3070 3071:switch:`-gnatwh` 3072 *Activate warnings on hiding.* 3073 3074 .. index:: Hiding of Declarations 3075 3076 This switch activates warnings on hiding declarations that are considered 3077 potentially confusing. Not all cases of hiding cause warnings; for example an 3078 overriding declaration hides an implicit declaration, which is just normal 3079 code. The default is that warnings on hiding are not generated. 3080 3081 3082.. index:: -gnatwH (gcc) 3083 3084:switch:`-gnatwH` 3085 *Suppress warnings on hiding.* 3086 3087 This switch suppresses warnings on hiding declarations. 3088 3089 3090.. index:: -gnatw.h (gcc) 3091 3092:switch:`-gnatw.h` 3093 *Activate warnings on holes/gaps in records.* 3094 3095 .. index:: Record Representation (gaps) 3096 3097 This switch activates warnings on component clauses in record 3098 representation clauses that leave holes (gaps) in the record layout. 3099 If this warning option is active, then record representation clauses 3100 should specify a contiguous layout, adding unused fill fields if needed. 3101 3102 3103.. index:: -gnatw.H (gcc) 3104 3105:switch:`-gnatw.H` 3106 *Suppress warnings on holes/gaps in records.* 3107 3108 This switch suppresses warnings on component clauses in record 3109 representation clauses that leave holes (haps) in the record layout. 3110 3111 3112.. index:: -gnatwi (gcc) 3113 3114:switch:`-gnatwi` 3115 *Activate warnings on implementation units.* 3116 3117 This switch activates warnings for a |with| of an internal GNAT 3118 implementation unit, defined as any unit from the ``Ada``, 3119 ``Interfaces``, ``GNAT``, 3120 or ``System`` 3121 hierarchies that is not 3122 documented in either the Ada Reference Manual or the GNAT 3123 Programmer's Reference Manual. Such units are intended only 3124 for internal implementation purposes and should not be |withed| 3125 by user programs. The default is that such warnings are generated 3126 3127 3128.. index:: -gnatwI (gcc) 3129 3130:switch:`-gnatwI` 3131 *Disable warnings on implementation units.* 3132 3133 This switch disables warnings for a |with| of an internal GNAT 3134 implementation unit. 3135 3136 3137.. index:: -gnatw.i (gcc) 3138 3139:switch:`-gnatw.i` 3140 *Activate warnings on overlapping actuals.* 3141 3142 This switch enables a warning on statically detectable overlapping actuals in 3143 a subprogram call, when one of the actuals is an in-out parameter, and the 3144 types of the actuals are not by-copy types. This warning is off by default. 3145 3146 3147.. index:: -gnatw.I (gcc) 3148 3149:switch:`-gnatw.I` 3150 *Disable warnings on overlapping actuals.* 3151 3152 This switch disables warnings on overlapping actuals in a call.. 3153 3154 3155.. index:: -gnatwj (gcc) 3156 3157:switch:`-gnatwj` 3158 *Activate warnings on obsolescent features (Annex J).* 3159 3160 .. index:: Features, obsolescent 3161 3162 .. index:: Obsolescent features 3163 3164 If this warning option is activated, then warnings are generated for 3165 calls to subprograms marked with ``pragma Obsolescent`` and 3166 for use of features in Annex J of the Ada Reference Manual. In the 3167 case of Annex J, not all features are flagged. In particular use 3168 of the renamed packages (like ``Text_IO``) and use of package 3169 ``ASCII`` are not flagged, since these are very common and 3170 would generate many annoying positive warnings. The default is that 3171 such warnings are not generated. 3172 3173 In addition to the above cases, warnings are also generated for 3174 GNAT features that have been provided in past versions but which 3175 have been superseded (typically by features in the new Ada standard). 3176 For example, ``pragma Ravenscar`` will be flagged since its 3177 function is replaced by ``pragma Profile(Ravenscar)``, and 3178 ``pragma Interface_Name`` will be flagged since its function 3179 is replaced by ``pragma Import``. 3180 3181 Note that this warning option functions differently from the 3182 restriction ``No_Obsolescent_Features`` in two respects. 3183 First, the restriction applies only to annex J features. 3184 Second, the restriction does flag uses of package ``ASCII``. 3185 3186 3187.. index:: -gnatwJ (gcc) 3188 3189:switch:`-gnatwJ` 3190 *Suppress warnings on obsolescent features (Annex J).* 3191 3192 This switch disables warnings on use of obsolescent features. 3193 3194 3195.. index:: -gnatw.j (gcc) 3196 3197:switch:`-gnatw.j` 3198 *Activate warnings on late declarations of tagged type primitives.* 3199 3200 This switch activates warnings on visible primitives added to a 3201 tagged type after deriving a private extension from it. 3202 3203 3204.. index:: -gnatw.J (gcc) 3205 3206:switch:`-gnatw.J` 3207 *Suppress warnings on late declarations of tagged type primitives.* 3208 3209 This switch suppresses warnings on visible primitives added to a 3210 tagged type after deriving a private extension from it. 3211 3212 3213.. index:: -gnatwk (gcc) 3214 3215:switch:`-gnatwk` 3216 *Activate warnings on variables that could be constants.* 3217 3218 This switch activates warnings for variables that are initialized but 3219 never modified, and then could be declared constants. The default is that 3220 such warnings are not given. 3221 3222 3223.. index:: -gnatwK (gcc) 3224 3225:switch:`-gnatwK` 3226 *Suppress warnings on variables that could be constants.* 3227 3228 This switch disables warnings on variables that could be declared constants. 3229 3230 3231.. index:: -gnatw.k (gcc) 3232 3233:switch:`-gnatw.k` 3234 *Activate warnings on redefinition of names in standard.* 3235 3236 This switch activates warnings for declarations that declare a name that 3237 is defined in package Standard. Such declarations can be confusing, 3238 especially since the names in package Standard continue to be directly 3239 visible, meaning that use visibiliy on such redeclared names does not 3240 work as expected. Names of discriminants and components in records are 3241 not included in this check. 3242 3243 3244.. index:: -gnatwK (gcc) 3245 3246:switch:`-gnatw.K` 3247 *Suppress warnings on redefinition of names in standard.* 3248 3249 This switch activates warnings for declarations that declare a name that 3250 is defined in package Standard. 3251 3252 3253.. index:: -gnatwl (gcc) 3254 3255:switch:`-gnatwl` 3256 *Activate warnings for elaboration pragmas.* 3257 3258 .. index:: Elaboration, warnings 3259 3260 This switch activates warnings for possible elaboration problems, 3261 including suspicious use 3262 of ``Elaborate`` pragmas, when using the static elaboration model, and 3263 possible situations that may raise ``Program_Error`` when using the 3264 dynamic elaboration model. 3265 See the section in this guide on elaboration checking for further details. 3266 The default is that such warnings 3267 are not generated. 3268 3269 3270.. index:: -gnatwL (gcc) 3271 3272:switch:`-gnatwL` 3273 *Suppress warnings for elaboration pragmas.* 3274 3275 This switch suppresses warnings for possible elaboration problems. 3276 3277 3278.. index:: -gnatw.l (gcc) 3279 3280:switch:`-gnatw.l` 3281 *List inherited aspects.* 3282 3283 This switch causes the compiler to list inherited invariants, 3284 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class, 3285 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates. 3286 3287 3288.. index:: -gnatw.L (gcc) 3289 3290:switch:`-gnatw.L` 3291 *Suppress listing of inherited aspects.* 3292 3293 This switch suppresses listing of inherited aspects. 3294 3295 3296.. index:: -gnatwm (gcc) 3297 3298:switch:`-gnatwm` 3299 *Activate warnings on modified but unreferenced variables.* 3300 3301 This switch activates warnings for variables that are assigned (using 3302 an initialization value or with one or more assignment statements) but 3303 whose value is never read. The warning is suppressed for volatile 3304 variables and also for variables that are renamings of other variables 3305 or for which an address clause is given. 3306 The default is that these warnings are not given. 3307 3308 3309.. index:: -gnatwM (gcc) 3310 3311:switch:`-gnatwM` 3312 *Disable warnings on modified but unreferenced variables.* 3313 3314 This switch disables warnings for variables that are assigned or 3315 initialized, but never read. 3316 3317 3318.. index:: -gnatw.m (gcc) 3319 3320:switch:`-gnatw.m` 3321 *Activate warnings on suspicious modulus values.* 3322 3323 This switch activates warnings for modulus values that seem suspicious. 3324 The cases caught are where the size is the same as the modulus (e.g. 3325 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 3326 with no size clause. The guess in both cases is that 2**x was intended 3327 rather than x. In addition expressions of the form 2*x for small x 3328 generate a warning (the almost certainly accurate guess being that 3329 2**x was intended). The default is that these warnings are given. 3330 3331 3332.. index:: -gnatw.M (gcc) 3333 3334:switch:`-gnatw.M` 3335 *Disable warnings on suspicious modulus values.* 3336 3337 This switch disables warnings for suspicious modulus values. 3338 3339 3340.. index:: -gnatwn (gcc) 3341 3342:switch:`-gnatwn` 3343 *Set normal warnings mode.* 3344 3345 This switch sets normal warning mode, in which enabled warnings are 3346 issued and treated as warnings rather than errors. This is the default 3347 mode. the switch :switch:`-gnatwn` can be used to cancel the effect of 3348 an explicit :switch:`-gnatws` or 3349 :switch:`-gnatwe`. It also cancels the effect of the 3350 implicit :switch:`-gnatwe` that is activated by the 3351 use of :switch:`-gnatg`. 3352 3353 3354.. index:: -gnatw.n (gcc) 3355.. index:: Atomic Synchronization, warnings 3356 3357:switch:`-gnatw.n` 3358 *Activate warnings on atomic synchronization.* 3359 3360 This switch actives warnings when an access to an atomic variable 3361 requires the generation of atomic synchronization code. These 3362 warnings are off by default. 3363 3364.. index:: -gnatw.N (gcc) 3365 3366:switch:`-gnatw.N` 3367 *Suppress warnings on atomic synchronization.* 3368 3369 .. index:: Atomic Synchronization, warnings 3370 3371 This switch suppresses warnings when an access to an atomic variable 3372 requires the generation of atomic synchronization code. 3373 3374 3375.. index:: -gnatwo (gcc) 3376.. index:: Address Clauses, warnings 3377 3378:switch:`-gnatwo` 3379 *Activate warnings on address clause overlays.* 3380 3381 This switch activates warnings for possibly unintended initialization 3382 effects of defining address clauses that cause one variable to overlap 3383 another. The default is that such warnings are generated. 3384 3385 3386.. index:: -gnatwO (gcc) 3387 3388:switch:`-gnatwO` 3389 *Suppress warnings on address clause overlays.* 3390 3391 This switch suppresses warnings on possibly unintended initialization 3392 effects of defining address clauses that cause one variable to overlap 3393 another. 3394 3395 3396.. index:: -gnatw.o (gcc) 3397 3398:switch:`-gnatw.o` 3399 *Activate warnings on modified but unreferenced out parameters.* 3400 3401 This switch activates warnings for variables that are modified by using 3402 them as actuals for a call to a procedure with an out mode formal, where 3403 the resulting assigned value is never read. It is applicable in the case 3404 where there is more than one out mode formal. If there is only one out 3405 mode formal, the warning is issued by default (controlled by -gnatwu). 3406 The warning is suppressed for volatile 3407 variables and also for variables that are renamings of other variables 3408 or for which an address clause is given. 3409 The default is that these warnings are not given. 3410 3411 3412.. index:: -gnatw.O (gcc) 3413 3414:switch:`-gnatw.O` 3415 *Disable warnings on modified but unreferenced out parameters.* 3416 3417 This switch suppresses warnings for variables that are modified by using 3418 them as actuals for a call to a procedure with an out mode formal, where 3419 the resulting assigned value is never read. 3420 3421 3422.. index:: -gnatwp (gcc) 3423.. index:: Inlining, warnings 3424 3425:switch:`-gnatwp` 3426 *Activate warnings on ineffective pragma Inlines.* 3427 3428 This switch activates warnings for failure of front end inlining 3429 (activated by :switch:`-gnatN`) to inline a particular call. There are 3430 many reasons for not being able to inline a call, including most 3431 commonly that the call is too complex to inline. The default is 3432 that such warnings are not given. 3433 Warnings on ineffective inlining by the gcc back-end can be activated 3434 separately, using the gcc switch -Winline. 3435 3436 3437.. index:: -gnatwP (gcc) 3438 3439:switch:`-gnatwP` 3440 *Suppress warnings on ineffective pragma Inlines.* 3441 3442 This switch suppresses warnings on ineffective pragma Inlines. If the 3443 inlining mechanism cannot inline a call, it will simply ignore the 3444 request silently. 3445 3446 3447.. index:: -gnatw.p (gcc) 3448.. index:: Parameter order, warnings 3449 3450:switch:`-gnatw.p` 3451 *Activate warnings on parameter ordering.* 3452 3453 This switch activates warnings for cases of suspicious parameter 3454 ordering when the list of arguments are all simple identifiers that 3455 match the names of the formals, but are in a different order. The 3456 warning is suppressed if any use of named parameter notation is used, 3457 so this is the appropriate way to suppress a false positive (and 3458 serves to emphasize that the "misordering" is deliberate). The 3459 default is that such warnings are not given. 3460 3461 3462.. index:: -gnatw.P (gcc) 3463 3464:switch:`-gnatw.P` 3465 *Suppress warnings on parameter ordering.* 3466 3467 This switch suppresses warnings on cases of suspicious parameter 3468 ordering. 3469 3470 3471.. index:: -gnatwq (gcc) 3472.. index:: Parentheses, warnings 3473 3474:switch:`-gnatwq` 3475 *Activate warnings on questionable missing parentheses.* 3476 3477 This switch activates warnings for cases where parentheses are not used and 3478 the result is potential ambiguity from a readers point of view. For example 3479 (not a > b) when a and b are modular means ((not a) > b) and very likely the 3480 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and 3481 quite likely ((-x) mod 5) was intended. In such situations it seems best to 3482 follow the rule of always parenthesizing to make the association clear, and 3483 this warning switch warns if such parentheses are not present. The default 3484 is that these warnings are given. 3485 3486 3487.. index:: -gnatwQ (gcc) 3488 3489:switch:`-gnatwQ` 3490 *Suppress warnings on questionable missing parentheses.* 3491 3492 This switch suppresses warnings for cases where the association is not 3493 clear and the use of parentheses is preferred. 3494 3495 3496.. index:: -gnatw.q (gcc) 3497.. index:: Layout, warnings 3498 3499:switch:`-gnatw.q` 3500 *Activate warnings on questionable layout of record types.* 3501 3502 This switch activates warnings for cases where the default layout of 3503 a record type, that is to say the layout of its components in textual 3504 order of the source code, would very likely cause inefficiencies in 3505 the code generated by the compiler, both in terms of space and speed 3506 during execution. One warning is issued for each problematic component 3507 without representation clause in the nonvariant part and then in each 3508 variant recursively, if any. 3509 3510 The purpose of these warnings is neither to prescribe an optimal layout 3511 nor to force the use of representation clauses, but rather to get rid of 3512 the most blatant inefficiencies in the layout. Therefore, the default 3513 layout is matched against the following synthetic ordered layout and 3514 the deviations are flagged on a component-by-component basis: 3515 3516 * first all components or groups of components whose length is fixed 3517 and a multiple of the storage unit, 3518 3519 * then the remaining components whose length is fixed and not a multiple 3520 of the storage unit, 3521 3522 * then the remaining components whose length doesn't depend on discriminants 3523 (that is to say, with variable but uniform length for all objects), 3524 3525 * then all components whose length depends on discriminants, 3526 3527 * finally the variant part (if any), 3528 3529 for the nonvariant part and for each variant recursively, if any. 3530 3531 The exact wording of the warning depends on whether the compiler is allowed 3532 to reorder the components in the record type or precluded from doing it by 3533 means of pragma ``No_Component_Reordering``. 3534 3535 The default is that these warnings are not given. 3536 3537.. index:: -gnatw.Q (gcc) 3538 3539:switch:`-gnatw.Q` 3540 *Suppress warnings on questionable layout of record types.* 3541 3542 This switch suppresses warnings for cases where the default layout of 3543 a record type would very likely cause inefficiencies. 3544 3545 3546.. index:: -gnatwr (gcc) 3547 3548:switch:`-gnatwr` 3549 *Activate warnings on redundant constructs.* 3550 3551 This switch activates warnings for redundant constructs. The following 3552 is the current list of constructs regarded as redundant: 3553 3554 * Assignment of an item to itself. 3555 3556 * Type conversion that converts an expression to its own type. 3557 3558 * Use of the attribute ``Base`` where ``typ'Base`` is the same 3559 as ``typ``. 3560 3561 * Use of pragma ``Pack`` when all components are placed by a record 3562 representation clause. 3563 3564 * Exception handler containing only a reraise statement (raise with no 3565 operand) which has no effect. 3566 3567 * Use of the operator abs on an operand that is known at compile time 3568 to be non-negative 3569 3570 * Comparison of an object or (unary or binary) operation of boolean type to 3571 an explicit True value. 3572 3573 The default is that warnings for redundant constructs are not given. 3574 3575 3576.. index:: -gnatwR (gcc) 3577 3578:switch:`-gnatwR` 3579 *Suppress warnings on redundant constructs.* 3580 3581 This switch suppresses warnings for redundant constructs. 3582 3583 3584.. index:: -gnatw.r (gcc) 3585 3586:switch:`-gnatw.r` 3587 *Activate warnings for object renaming function.* 3588 3589 This switch activates warnings for an object renaming that renames a 3590 function call, which is equivalent to a constant declaration (as 3591 opposed to renaming the function itself). The default is that these 3592 warnings are given. 3593 3594 3595.. index:: -gnatwT (gcc) 3596 3597:switch:`-gnatw.R` 3598 *Suppress warnings for object renaming function.* 3599 3600 This switch suppresses warnings for object renaming function. 3601 3602 3603.. index:: -gnatws (gcc) 3604 3605:switch:`-gnatws` 3606 *Suppress all warnings.* 3607 3608 This switch completely suppresses the 3609 output of all warning messages from the GNAT front end, including 3610 both warnings that can be controlled by switches described in this 3611 section, and those that are normally given unconditionally. The 3612 effect of this suppress action can only be cancelled by a subsequent 3613 use of the switch :switch:`-gnatwn`. 3614 3615 Note that switch :switch:`-gnatws` does not suppress 3616 warnings from the ``gcc`` back end. 3617 To suppress these back end warnings as well, use the switch :switch:`-w` 3618 in addition to :switch:`-gnatws`. Also this switch has no effect on the 3619 handling of style check messages. 3620 3621 3622.. index:: -gnatw.s (gcc) 3623.. index:: Record Representation (component sizes) 3624 3625:switch:`-gnatw.s` 3626 *Activate warnings on overridden size clauses.* 3627 3628 This switch activates warnings on component clauses in record 3629 representation clauses where the length given overrides that 3630 specified by an explicit size clause for the component type. A 3631 warning is similarly given in the array case if a specified 3632 component size overrides an explicit size clause for the array 3633 component type. 3634 3635 3636.. index:: -gnatw.S (gcc) 3637 3638:switch:`-gnatw.S` 3639 *Suppress warnings on overridden size clauses.* 3640 3641 This switch suppresses warnings on component clauses in record 3642 representation clauses that override size clauses, and similar 3643 warnings when an array component size overrides a size clause. 3644 3645 3646.. index:: -gnatwt (gcc) 3647.. index:: Deactivated code, warnings 3648.. index:: Deleted code, warnings 3649 3650:switch:`-gnatwt` 3651 *Activate warnings for tracking of deleted conditional code.* 3652 3653 This switch activates warnings for tracking of code in conditionals (IF and 3654 CASE statements) that is detected to be dead code which cannot be executed, and 3655 which is removed by the front end. This warning is off by default. This may be 3656 useful for detecting deactivated code in certified applications. 3657 3658 3659.. index:: -gnatwT (gcc) 3660 3661:switch:`-gnatwT` 3662 *Suppress warnings for tracking of deleted conditional code.* 3663 3664 This switch suppresses warnings for tracking of deleted conditional code. 3665 3666 3667.. index:: -gnatw.t (gcc) 3668 3669:switch:`-gnatw.t` 3670 *Activate warnings on suspicious contracts.* 3671 3672 This switch activates warnings on suspicious contracts. This includes 3673 warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a 3674 ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect 3675 ``Contract_Cases``). A function postcondition or contract case is suspicious 3676 when no postcondition or contract case for this function mentions the result 3677 of the function. A procedure postcondition or contract case is suspicious 3678 when it only refers to the pre-state of the procedure, because in that case 3679 it should rather be expressed as a precondition. This switch also controls 3680 warnings on suspicious cases of expressions typically found in contracts like 3681 quantified expressions and uses of Update attribute. The default is that such 3682 warnings are generated. 3683 3684 3685.. index:: -gnatw.T (gcc) 3686 3687:switch:`-gnatw.T` 3688 *Suppress warnings on suspicious contracts.* 3689 3690 This switch suppresses warnings on suspicious contracts. 3691 3692 3693.. index:: -gnatwu (gcc) 3694 3695:switch:`-gnatwu` 3696 *Activate warnings on unused entities.* 3697 3698 This switch activates warnings to be generated for entities that 3699 are declared but not referenced, and for units that are |withed| 3700 and not 3701 referenced. In the case of packages, a warning is also generated if 3702 no entities in the package are referenced. This means that if a with'ed 3703 package is referenced but the only references are in ``use`` 3704 clauses or ``renames`` 3705 declarations, a warning is still generated. A warning is also generated 3706 for a generic package that is |withed| but never instantiated. 3707 In the case where a package or subprogram body is compiled, and there 3708 is a |with| on the corresponding spec 3709 that is only referenced in the body, 3710 a warning is also generated, noting that the 3711 |with| can be moved to the body. The default is that 3712 such warnings are not generated. 3713 This switch also activates warnings on unreferenced formals 3714 (it includes the effect of :switch:`-gnatwf`). 3715 3716 3717.. index:: -gnatwU (gcc) 3718 3719:switch:`-gnatwU` 3720 *Suppress warnings on unused entities.* 3721 3722 This switch suppresses warnings for unused entities and packages. 3723 It also turns off warnings on unreferenced formals (and thus includes 3724 the effect of :switch:`-gnatwF`). 3725 3726 3727.. index:: -gnatw.u (gcc) 3728 3729:switch:`-gnatw.u` 3730 *Activate warnings on unordered enumeration types.* 3731 3732 This switch causes enumeration types to be considered as conceptually 3733 unordered, unless an explicit pragma ``Ordered`` is given for the type. 3734 The effect is to generate warnings in clients that use explicit comparisons 3735 or subranges, since these constructs both treat objects of the type as 3736 ordered. (A *client* is defined as a unit that is other than the unit in 3737 which the type is declared, or its body or subunits.) Please refer to 3738 the description of pragma ``Ordered`` in the 3739 :title:`GNAT Reference Manual` for further details. 3740 The default is that such warnings are not generated. 3741 3742 3743.. index:: -gnatw.U (gcc) 3744 3745:switch:`-gnatw.U` 3746 *Deactivate warnings on unordered enumeration types.* 3747 3748 This switch causes all enumeration types to be considered as ordered, so 3749 that no warnings are given for comparisons or subranges for any type. 3750 3751 3752.. index:: -gnatwv (gcc) 3753.. index:: Unassigned variable warnings 3754 3755:switch:`-gnatwv` 3756 *Activate warnings on unassigned variables.* 3757 3758 This switch activates warnings for access to variables which 3759 may not be properly initialized. The default is that 3760 such warnings are generated. 3761 3762 3763.. index:: -gnatwV (gcc) 3764 3765:switch:`-gnatwV` 3766 *Suppress warnings on unassigned variables.* 3767 3768 This switch suppresses warnings for access to variables which 3769 may not be properly initialized. 3770 For variables of a composite type, the warning can also be suppressed in 3771 Ada 2005 by using a default initialization with a box. For example, if 3772 Table is an array of records whose components are only partially uninitialized, 3773 then the following code: 3774 3775 .. code-block:: ada 3776 3777 Tab : Table := (others => <>); 3778 3779 will suppress warnings on subsequent statements that access components 3780 of variable Tab. 3781 3782 3783.. index:: -gnatw.v (gcc) 3784.. index:: bit order warnings 3785 3786:switch:`-gnatw.v` 3787 *Activate info messages for non-default bit order.* 3788 3789 This switch activates messages (labeled "info", they are not warnings, 3790 just informational messages) about the effects of non-default bit-order 3791 on records to which a component clause is applied. The effect of specifying 3792 non-default bit ordering is a bit subtle (and changed with Ada 2005), so 3793 these messages, which are given by default, are useful in understanding the 3794 exact consequences of using this feature. 3795 3796 3797.. index:: -gnatw.V (gcc) 3798 3799:switch:`-gnatw.V` 3800 *Suppress info messages for non-default bit order.* 3801 3802 This switch suppresses information messages for the effects of specifying 3803 non-default bit order on record components with component clauses. 3804 3805 3806.. index:: -gnatww (gcc) 3807.. index:: String indexing warnings 3808 3809:switch:`-gnatww` 3810 *Activate warnings on wrong low bound assumption.* 3811 3812 This switch activates warnings for indexing an unconstrained string parameter 3813 with a literal or S'Length. This is a case where the code is assuming that the 3814 low bound is one, which is in general not true (for example when a slice is 3815 passed). The default is that such warnings are generated. 3816 3817 3818.. index:: -gnatwW (gcc) 3819 3820:switch:`-gnatwW` 3821 *Suppress warnings on wrong low bound assumption.* 3822 3823 This switch suppresses warnings for indexing an unconstrained string parameter 3824 with a literal or S'Length. Note that this warning can also be suppressed 3825 in a particular case by adding an assertion that the lower bound is 1, 3826 as shown in the following example: 3827 3828 .. code-block:: ada 3829 3830 procedure K (S : String) is 3831 pragma Assert (S'First = 1); 3832 ... 3833 3834 3835.. index:: -gnatw.w (gcc) 3836.. index:: Warnings Off control 3837 3838:switch:`-gnatw.w` 3839 *Activate warnings on Warnings Off pragmas.* 3840 3841 This switch activates warnings for use of ``pragma Warnings (Off, entity)`` 3842 where either the pragma is entirely useless (because it suppresses no 3843 warnings), or it could be replaced by ``pragma Unreferenced`` or 3844 ``pragma Unmodified``. 3845 Also activates warnings for the case of 3846 Warnings (Off, String), where either there is no matching 3847 Warnings (On, String), or the Warnings (Off) did not suppress any warning. 3848 The default is that these warnings are not given. 3849 3850 3851.. index:: -gnatw.W (gcc) 3852 3853:switch:`-gnatw.W` 3854 *Suppress warnings on unnecessary Warnings Off pragmas.* 3855 3856 This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``. 3857 3858 3859.. index:: -gnatwx (gcc) 3860.. index:: Export/Import pragma warnings 3861 3862:switch:`-gnatwx` 3863 *Activate warnings on Export/Import pragmas.* 3864 3865 This switch activates warnings on Export/Import pragmas when 3866 the compiler detects a possible conflict between the Ada and 3867 foreign language calling sequences. For example, the use of 3868 default parameters in a convention C procedure is dubious 3869 because the C compiler cannot supply the proper default, so 3870 a warning is issued. The default is that such warnings are 3871 generated. 3872 3873 3874.. index:: -gnatwX (gcc) 3875 3876:switch:`-gnatwX` 3877 *Suppress warnings on Export/Import pragmas.* 3878 3879 This switch suppresses warnings on Export/Import pragmas. 3880 The sense of this is that you are telling the compiler that 3881 you know what you are doing in writing the pragma, and it 3882 should not complain at you. 3883 3884 3885.. index:: -gnatwm (gcc) 3886 3887:switch:`-gnatw.x` 3888 *Activate warnings for No_Exception_Propagation mode.* 3889 3890 This switch activates warnings for exception usage when pragma Restrictions 3891 (No_Exception_Propagation) is in effect. Warnings are given for implicit or 3892 explicit exception raises which are not covered by a local handler, and for 3893 exception handlers which do not cover a local raise. The default is that 3894 these warnings are given for units that contain exception handlers. 3895 3896 3897:switch:`-gnatw.X` 3898 *Disable warnings for No_Exception_Propagation mode.* 3899 3900 This switch disables warnings for exception usage when pragma Restrictions 3901 (No_Exception_Propagation) is in effect. 3902 3903 3904.. index:: -gnatwy (gcc) 3905.. index:: Ada compatibility issues warnings 3906 3907:switch:`-gnatwy` 3908 *Activate warnings for Ada compatibility issues.* 3909 3910 For the most part, newer versions of Ada are upwards compatible 3911 with older versions. For example, Ada 2005 programs will almost 3912 always work when compiled as Ada 2012. 3913 However there are some exceptions (for example the fact that 3914 ``some`` is now a reserved word in Ada 2012). This 3915 switch activates several warnings to help in identifying 3916 and correcting such incompatibilities. The default is that 3917 these warnings are generated. Note that at one point Ada 2005 3918 was called Ada 0Y, hence the choice of character. 3919 3920 3921.. index:: -gnatwY (gcc) 3922.. index:: Ada compatibility issues warnings 3923 3924:switch:`-gnatwY` 3925 *Disable warnings for Ada compatibility issues.* 3926 3927 This switch suppresses the warnings intended to help in identifying 3928 incompatibilities between Ada language versions. 3929 3930 3931.. index:: -gnatw.y (gcc) 3932.. index:: Package spec needing body 3933 3934:switch:`-gnatw.y` 3935 *Activate information messages for why package spec needs body.* 3936 3937 There are a number of cases in which a package spec needs a body. 3938 For example, the use of pragma Elaborate_Body, or the declaration 3939 of a procedure specification requiring a completion. This switch 3940 causes information messages to be output showing why a package 3941 specification requires a body. This can be useful in the case of 3942 a large package specification which is unexpectedly requiring a 3943 body. The default is that such information messages are not output. 3944 3945 3946.. index:: -gnatw.Y (gcc) 3947.. index:: No information messages for why package spec needs body 3948 3949:switch:`-gnatw.Y` 3950 *Disable information messages for why package spec needs body.* 3951 3952 This switch suppresses the output of information messages showing why 3953 a package specification needs a body. 3954 3955 3956.. index:: -gnatwz (gcc) 3957.. index:: Unchecked_Conversion warnings 3958 3959:switch:`-gnatwz` 3960 *Activate warnings on unchecked conversions.* 3961 3962 This switch activates warnings for unchecked conversions 3963 where the types are known at compile time to have different 3964 sizes. The default is that such warnings are generated. Warnings are also 3965 generated for subprogram pointers with different conventions. 3966 3967 3968.. index:: -gnatwZ (gcc) 3969 3970:switch:`-gnatwZ` 3971 *Suppress warnings on unchecked conversions.* 3972 3973 This switch suppresses warnings for unchecked conversions 3974 where the types are known at compile time to have different 3975 sizes or conventions. 3976 3977 3978.. index:: -gnatw.z (gcc) 3979.. index:: Size/Alignment warnings 3980 3981:switch:`-gnatw.z` 3982 *Activate warnings for size not a multiple of alignment.* 3983 3984 This switch activates warnings for cases of record types with 3985 specified ``Size`` and ``Alignment`` attributes where the 3986 size is not a multiple of the alignment, resulting in an object 3987 size that is greater than the specified size. The default 3988 is that such warnings are generated. 3989 3990 3991.. index:: -gnatw.Z (gcc) 3992.. index:: Size/Alignment warnings 3993 3994:switch:`-gnatw.Z` 3995 *Suppress warnings for size not a multiple of alignment.* 3996 3997 This switch suppresses warnings for cases of record types with 3998 specified ``Size`` and ``Alignment`` attributes where the 3999 size is not a multiple of the alignment, resulting in an object 4000 size that is greater than the specified size. 4001 The warning can also be 4002 suppressed by giving an explicit ``Object_Size`` value. 4003 4004 4005.. index:: -Wunused (gcc) 4006 4007:switch:`-Wunused` 4008 The warnings controlled by the :switch:`-gnatw` switch are generated by 4009 the front end of the compiler. The GCC back end can provide 4010 additional warnings and they are controlled by the :switch:`-W` switch. 4011 For example, :switch:`-Wunused` activates back end 4012 warnings for entities that are declared but not referenced. 4013 4014 4015.. index:: -Wuninitialized (gcc) 4016 4017:switch:`-Wuninitialized` 4018 Similarly, :switch:`-Wuninitialized` activates 4019 the back end warning for uninitialized variables. This switch must be 4020 used in conjunction with an optimization level greater than zero. 4021 4022 4023.. index:: -Wstack-usage (gcc) 4024 4025:switch:`-Wstack-usage={len}` 4026 Warn if the stack usage of a subprogram might be larger than ``len`` bytes. 4027 See :ref:`Static_Stack_Usage_Analysis` for details. 4028 4029 4030.. index:: -Wall (gcc) 4031 4032:switch:`-Wall` 4033 This switch enables most warnings from the GCC back end. 4034 The code generator detects a number of warning situations that are missed 4035 by the GNAT front end, and this switch can be used to activate them. 4036 The use of this switch also sets the default front end warning mode to 4037 :switch:`-gnatwa`, that is, most front end warnings activated as well. 4038 4039 4040.. index:: -w (gcc) 4041 4042:switch:`-w` 4043 Conversely, this switch suppresses warnings from the GCC back end. 4044 The use of this switch also sets the default front end warning mode to 4045 :switch:`-gnatws`, that is, front end warnings suppressed as well. 4046 4047 4048.. index:: -Werror (gcc) 4049 4050:switch:`-Werror` 4051 This switch causes warnings from the GCC back end to be treated as 4052 errors. The warning string still appears, but the warning messages are 4053 counted as errors, and prevent the generation of an object file. 4054 4055 4056A string of warning parameters can be used in the same parameter. For example:: 4057 4058 -gnatwaGe 4059 4060 4061will turn on all optional warnings except for unrecognized pragma warnings, 4062and also specify that warnings should be treated as errors. 4063 4064When no switch :switch:`-gnatw` is used, this is equivalent to: 4065 4066 * :switch:`-gnatw.a` 4067 4068 * :switch:`-gnatwB` 4069 4070 * :switch:`-gnatw.b` 4071 4072 * :switch:`-gnatwC` 4073 4074 * :switch:`-gnatw.C` 4075 4076 * :switch:`-gnatwD` 4077 4078 * :switch:`-gnatw.D` 4079 4080 * :switch:`-gnatwF` 4081 4082 * :switch:`-gnatw.F` 4083 4084 * :switch:`-gnatwg` 4085 4086 * :switch:`-gnatwH` 4087 4088 * :switch:`-gnatw.H` 4089 4090 * :switch:`-gnatwi` 4091 4092 * :switch:`-gnatwJ` 4093 4094 * :switch:`-gnatw.J` 4095 4096 * :switch:`-gnatwK` 4097 4098 * :switch:`-gnatw.K` 4099 4100 * :switch:`-gnatwL` 4101 4102 * :switch:`-gnatw.L` 4103 4104 * :switch:`-gnatwM` 4105 4106 * :switch:`-gnatw.m` 4107 4108 * :switch:`-gnatwn` 4109 4110 * :switch:`-gnatw.N` 4111 4112 * :switch:`-gnatwo` 4113 4114 * :switch:`-gnatw.O` 4115 4116 * :switch:`-gnatwP` 4117 4118 * :switch:`-gnatw.P` 4119 4120 * :switch:`-gnatwq` 4121 4122 * :switch:`-gnatw.Q` 4123 4124 * :switch:`-gnatwR` 4125 4126 * :switch:`-gnatw.R` 4127 4128 * :switch:`-gnatw.S` 4129 4130 * :switch:`-gnatwT` 4131 4132 * :switch:`-gnatw.t` 4133 4134 * :switch:`-gnatwU` 4135 4136 * :switch:`-gnatw.U` 4137 4138 * :switch:`-gnatwv` 4139 4140 * :switch:`-gnatw.v` 4141 4142 * :switch:`-gnatww` 4143 4144 * :switch:`-gnatw.W` 4145 4146 * :switch:`-gnatwx` 4147 4148 * :switch:`-gnatw.X` 4149 4150 * :switch:`-gnatwy` 4151 4152 * :switch:`-gnatw.Y` 4153 4154 * :switch:`-gnatwz` 4155 4156 * :switch:`-gnatw.z` 4157 4158.. _Debugging_and_Assertion_Control: 4159 4160Debugging and Assertion Control 4161------------------------------- 4162 4163 4164 4165.. index:: -gnata (gcc) 4166 4167:switch:`-gnata` 4168 .. index:: Assert 4169 .. index:: Debug 4170 .. index:: Assertions 4171 .. index:: Precondition 4172 .. index:: Postcondition 4173 .. index:: Type invariants 4174 .. index:: Subtype predicates 4175 4176 The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma:: 4177 4178 pragma Assertion_Policy (Check); 4179 4180 Which is a shorthand for:: 4181 4182 pragma Assertion_Policy 4183 (Assert => Check, 4184 Static_Predicate => Check, 4185 Dynamic_Predicate => Check, 4186 Pre => Check, 4187 Pre'Class => Check, 4188 Post => Check, 4189 Post'Class => Check, 4190 Type_Invariant => Check, 4191 Type_Invariant'Class => Check); 4192 4193 The pragmas ``Assert`` and ``Debug`` normally have no effect and 4194 are ignored. This switch, where ``a`` stands for 'assert', causes 4195 pragmas ``Assert`` and ``Debug`` to be activated. This switch also 4196 causes preconditions, postconditions, subtype predicates, and 4197 type invariants to be activated. 4198 4199 The pragmas have the form:: 4200 4201 pragma Assert (<Boolean-expression> [, <static-string-expression>]) 4202 pragma Debug (<procedure call>) 4203 pragma Type_Invariant (<type-local-name>, <Boolean-expression>) 4204 pragma Predicate (<type-local-name>, <Boolean-expression>) 4205 pragma Precondition (<Boolean-expression>, <string-expression>) 4206 pragma Postcondition (<Boolean-expression>, <string-expression>) 4207 4208 The aspects have the form:: 4209 4210 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate] 4211 => <Boolean-expression>; 4212 4213 The ``Assert`` pragma causes ``Boolean-expression`` to be tested. 4214 If the result is ``True``, the pragma has no effect (other than 4215 possible side effects from evaluating the expression). If the result is 4216 ``False``, the exception ``Assert_Failure`` declared in the package 4217 ``System.Assertions`` is raised (passing ``static-string-expression``, if 4218 present, as the message associated with the exception). If no string 4219 expression is given, the default is a string containing the file name and 4220 line number of the pragma. 4221 4222 The ``Debug`` pragma causes ``procedure`` to be called. Note that 4223 ``pragma Debug`` may appear within a declaration sequence, allowing 4224 debugging procedures to be called between declarations. 4225 4226 For the aspect specification, the ``Boolean-expression`` is evaluated. 4227 If the result is ``True``, the aspect has no effect. If the result 4228 is ``False``, the exception ``Assert_Failure`` is raised. 4229 4230.. _Validity_Checking: 4231 4232Validity Checking 4233----------------- 4234 4235.. index:: Validity Checking 4236 4237The Ada Reference Manual defines the concept of invalid values (see 4238RM 13.9.1). The primary source of invalid values is uninitialized 4239variables. A scalar variable that is left uninitialized may contain 4240an invalid value; the concept of invalid does not apply to access or 4241composite types. 4242 4243It is an error to read an invalid value, but the RM does not require 4244run-time checks to detect such errors, except for some minimal 4245checking to prevent erroneous execution (i.e. unpredictable 4246behavior). This corresponds to the :switch:`-gnatVd` switch below, 4247which is the default. For example, by default, if the expression of a 4248case statement is invalid, it will raise Constraint_Error rather than 4249causing a wild jump, and if an array index on the left-hand side of an 4250assignment is invalid, it will raise Constraint_Error rather than 4251overwriting an arbitrary memory location. 4252 4253The :switch:`-gnatVa` may be used to enable additional validity checks, 4254which are not required by the RM. These checks are often very 4255expensive (which is why the RM does not require them). These checks 4256are useful in tracking down uninitialized variables, but they are 4257not usually recommended for production builds, and in particular 4258we do not recommend using these extra validity checking options in 4259combination with optimization, since this can confuse the optimizer. 4260If performance is a consideration, leading to the need to optimize, 4261then the validity checking options should not be used. 4262 4263The other :switch:`-gnatV{x}` switches below allow finer-grained 4264control; you can enable whichever validity checks you desire. However, 4265for most debugging purposes, :switch:`-gnatVa` is sufficient, and the 4266default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually 4267sufficient for non-debugging use. 4268 4269The :switch:`-gnatB` switch tells the compiler to assume that all 4270values are valid (that is, within their declared subtype range) 4271except in the context of a use of the Valid attribute. This means 4272the compiler can generate more efficient code, since the range 4273of values is better known at compile time. However, an uninitialized 4274variable can cause wild jumps and memory corruption in this mode. 4275 4276The :switch:`-gnatV{x}` switch allows control over the validity 4277checking mode as described below. 4278The ``x`` argument is a string of letters that 4279indicate validity checks that are performed or not performed in addition 4280to the default checks required by Ada as described above. 4281 4282 4283.. index:: -gnatVa (gcc) 4284 4285:switch:`-gnatVa` 4286 *All validity checks.* 4287 4288 All validity checks are turned on. 4289 That is, :switch:`-gnatVa` is 4290 equivalent to ``gnatVcdfimorst``. 4291 4292 4293.. index:: -gnatVc (gcc) 4294 4295:switch:`-gnatVc` 4296 *Validity checks for copies.* 4297 4298 The right hand side of assignments, and the initializing values of 4299 object declarations are validity checked. 4300 4301 4302.. index:: -gnatVd (gcc) 4303 4304:switch:`-gnatVd` 4305 *Default (RM) validity checks.* 4306 4307 Some validity checks are done by default following normal Ada semantics 4308 (RM 13.9.1 (9-11)). 4309 A check is done in case statements that the expression is within the range 4310 of the subtype. If it is not, Constraint_Error is raised. 4311 For assignments to array components, a check is done that the expression used 4312 as index is within the range. If it is not, Constraint_Error is raised. 4313 Both these validity checks may be turned off using switch :switch:`-gnatVD`. 4314 They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent 4315 switch :switch:`-gnatVd` will leave the checks turned on. 4316 Switch :switch:`-gnatVD` should be used only if you are sure that all such 4317 expressions have valid values. If you use this switch and invalid values 4318 are present, then the program is erroneous, and wild jumps or memory 4319 overwriting may occur. 4320 4321 4322.. index:: -gnatVe (gcc) 4323 4324:switch:`-gnatVe` 4325 *Validity checks for elementary components.* 4326 4327 In the absence of this switch, assignments to record or array components are 4328 not validity checked, even if validity checks for assignments generally 4329 (:switch:`-gnatVc`) are turned on. In Ada, assignment of composite values do not 4330 require valid data, but assignment of individual components does. So for 4331 example, there is a difference between copying the elements of an array with a 4332 slice assignment, compared to assigning element by element in a loop. This 4333 switch allows you to turn off validity checking for components, even when they 4334 are assigned component by component. 4335 4336 4337.. index:: -gnatVf (gcc) 4338 4339:switch:`-gnatVf` 4340 *Validity checks for floating-point values.* 4341 4342 In the absence of this switch, validity checking occurs only for discrete 4343 values. If :switch:`-gnatVf` is specified, then validity checking also applies 4344 for floating-point values, and NaNs and infinities are considered invalid, 4345 as well as out of range values for constrained types. Note that this means 4346 that standard IEEE infinity mode is not allowed. The exact contexts 4347 in which floating-point values are checked depends on the setting of other 4348 options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi` 4349 (the order does not matter) specifies that floating-point parameters of mode 4350 ``in`` should be validity checked. 4351 4352 4353.. index:: -gnatVi (gcc) 4354 4355:switch:`-gnatVi` 4356 *Validity checks for ``in`` mode parameters.* 4357 4358 Arguments for parameters of mode ``in`` are validity checked in function 4359 and procedure calls at the point of call. 4360 4361 4362.. index:: -gnatVm (gcc) 4363 4364:switch:`-gnatVm` 4365 *Validity checks for ``in out`` mode parameters.* 4366 4367 Arguments for parameters of mode ``in out`` are validity checked in 4368 procedure calls at the point of call. The ``'m'`` here stands for 4369 modify, since this concerns parameters that can be modified by the call. 4370 Note that there is no specific option to test ``out`` parameters, 4371 but any reference within the subprogram will be tested in the usual 4372 manner, and if an invalid value is copied back, any reference to it 4373 will be subject to validity checking. 4374 4375 4376.. index:: -gnatVn (gcc) 4377 4378:switch:`-gnatVn` 4379 *No validity checks.* 4380 4381 This switch turns off all validity checking, including the default checking 4382 for case statements and left hand side subscripts. Note that the use of 4383 the switch :switch:`-gnatp` suppresses all run-time checks, including 4384 validity checks, and thus implies :switch:`-gnatVn`. When this switch 4385 is used, it cancels any other :switch:`-gnatV` previously issued. 4386 4387 4388.. index:: -gnatVo (gcc) 4389 4390:switch:`-gnatVo` 4391 *Validity checks for operator and attribute operands.* 4392 4393 Arguments for predefined operators and attributes are validity checked. 4394 This includes all operators in package ``Standard``, 4395 the shift operators defined as intrinsic in package ``Interfaces`` 4396 and operands for attributes such as ``Pos``. Checks are also made 4397 on individual component values for composite comparisons, and on the 4398 expressions in type conversions and qualified expressions. Checks are 4399 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc). 4400 4401 4402.. index:: -gnatVp (gcc) 4403 4404:switch:`-gnatVp` 4405 *Validity checks for parameters.* 4406 4407 This controls the treatment of parameters within a subprogram (as opposed 4408 to :switch:`-gnatVi` and :switch:`-gnatVm` which control validity testing 4409 of parameters on a call. If either of these call options is used, then 4410 normally an assumption is made within a subprogram that the input arguments 4411 have been validity checking at the point of call, and do not need checking 4412 again within a subprogram). If :switch:`-gnatVp` is set, then this assumption 4413 is not made, and parameters are not assumed to be valid, so their validity 4414 will be checked (or rechecked) within the subprogram. 4415 4416 4417.. index:: -gnatVr (gcc) 4418 4419:switch:`-gnatVr` 4420 *Validity checks for function returns.* 4421 4422 The expression in ``return`` statements in functions is validity 4423 checked. 4424 4425 4426.. index:: -gnatVs (gcc) 4427 4428:switch:`-gnatVs` 4429 *Validity checks for subscripts.* 4430 4431 All subscripts expressions are checked for validity, whether they appear 4432 on the right side or left side (in default mode only left side subscripts 4433 are validity checked). 4434 4435 4436.. index:: -gnatVt (gcc) 4437 4438:switch:`-gnatVt` 4439 *Validity checks for tests.* 4440 4441 Expressions used as conditions in ``if``, ``while`` or ``exit`` 4442 statements are checked, as well as guard expressions in entry calls. 4443 4444 4445The :switch:`-gnatV` switch may be followed by a string of letters 4446to turn on a series of validity checking options. 4447For example, :switch:`-gnatVcr` 4448specifies that in addition to the default validity checking, copies and 4449function return expressions are to be validity checked. 4450In order to make it easier to specify the desired combination of effects, 4451the upper case letters ``CDFIMORST`` may 4452be used to turn off the corresponding lower case option. 4453Thus :switch:`-gnatVaM` turns on all validity checking options except for 4454checking of ``in out`` parameters. 4455 4456The specification of additional validity checking generates extra code (and 4457in the case of :switch:`-gnatVa` the code expansion can be substantial). 4458However, these additional checks can be very useful in detecting 4459uninitialized variables, incorrect use of unchecked conversion, and other 4460errors leading to invalid values. The use of pragma ``Initialize_Scalars`` 4461is useful in conjunction with the extra validity checking, since this 4462ensures that wherever possible uninitialized variables have invalid values. 4463 4464See also the pragma ``Validity_Checks`` which allows modification of 4465the validity checking mode at the program source level, and also allows for 4466temporary disabling of validity checks. 4467 4468.. _Style_Checking: 4469 4470Style Checking 4471-------------- 4472 4473.. index:: Style checking 4474 4475.. index:: -gnaty (gcc) 4476 4477The :switch:`-gnatyx` switch causes the compiler to 4478enforce specified style rules. A limited set of style rules has been used 4479in writing the GNAT sources themselves. This switch allows user programs 4480to activate all or some of these checks. If the source program fails a 4481specified style check, an appropriate message is given, preceded by 4482the character sequence '(style)'. This message does not prevent 4483successful compilation (unless the :switch:`-gnatwe` switch is used). 4484 4485Note that this is by no means intended to be a general facility for 4486checking arbitrary coding standards. It is simply an embedding of the 4487style rules we have chosen for the GNAT sources. If you are starting 4488a project which does not have established style standards, you may 4489find it useful to adopt the entire set of GNAT coding standards, or 4490some subset of them. 4491 4492.. only:: PRO or GPL 4493 4494 If you already have an established set of coding 4495 standards, then the selected style checking options may 4496 indeed correspond to choices you have made, but for general checking 4497 of an existing set of coding rules, you should look to the gnatcheck 4498 tool, which is designed for that purpose. 4499 4500The string ``x`` is a sequence of letters or digits 4501indicating the particular style 4502checks to be performed. The following checks are defined: 4503 4504 4505.. index:: -gnaty[0-9] (gcc) 4506 4507:switch:`-gnaty0` 4508 *Specify indentation level.* 4509 4510 If a digit from 1-9 appears 4511 in the string after :switch:`-gnaty` 4512 then proper indentation is checked, with the digit indicating the 4513 indentation level required. A value of zero turns off this style check. 4514 The general style of required indentation is as specified by 4515 the examples in the Ada Reference Manual. Full line comments must be 4516 aligned with the ``--`` starting on a column that is a multiple of 4517 the alignment level, or they may be aligned the same way as the following 4518 non-blank line (this is useful when full line comments appear in the middle 4519 of a statement, or they may be aligned with the source line on the previous 4520 non-blank line. 4521 4522.. index:: -gnatya (gcc) 4523 4524:switch:`-gnatya` 4525 *Check attribute casing.* 4526 4527 Attribute names, including the case of keywords such as ``digits`` 4528 used as attributes names, must be written in mixed case, that is, the 4529 initial letter and any letter following an underscore must be uppercase. 4530 All other letters must be lowercase. 4531 4532 4533.. index:: -gnatyA (gcc) 4534 4535:switch:`-gnatyA` 4536 *Use of array index numbers in array attributes.* 4537 4538 When using the array attributes First, Last, Range, 4539 or Length, the index number must be omitted for one-dimensional arrays 4540 and is required for multi-dimensional arrays. 4541 4542 4543.. index:: -gnatyb (gcc) 4544 4545:switch:`-gnatyb` 4546 *Blanks not allowed at statement end.* 4547 4548 Trailing blanks are not allowed at the end of statements. The purpose of this 4549 rule, together with h (no horizontal tabs), is to enforce a canonical format 4550 for the use of blanks to separate source tokens. 4551 4552 4553.. index:: -gnatyB (gcc) 4554 4555:switch:`-gnatyB` 4556 *Check Boolean operators.* 4557 4558 The use of AND/OR operators is not permitted except in the cases of modular 4559 operands, array operands, and simple stand-alone boolean variables or 4560 boolean constants. In all other cases ``and then``/`or else` are 4561 required. 4562 4563 4564.. index:: -gnatyc (gcc) 4565 4566:switch:`-gnatyc` 4567 *Check comments, double space.* 4568 4569 Comments must meet the following set of rules: 4570 4571 * The ``--`` that starts the column must either start in column one, 4572 or else at least one blank must precede this sequence. 4573 4574 * Comments that follow other tokens on a line must have at least one blank 4575 following the ``--`` at the start of the comment. 4576 4577 * Full line comments must have at least two blanks following the 4578 ``--`` that starts the comment, with the following exceptions. 4579 4580 * A line consisting only of the ``--`` characters, possibly preceded 4581 by blanks is permitted. 4582 4583 * A comment starting with ``--x`` where ``x`` is a special character 4584 is permitted. 4585 This allows proper processing of the output from specialized tools 4586 such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK 4587 annotation 4588 language (where ``--#`` is used). For the purposes of this rule, a 4589 special character is defined as being in one of the ASCII ranges 4590 ``16#21#...16#2F#`` or ``16#3A#...16#3F#``. 4591 Note that this usage is not permitted 4592 in GNAT implementation units (i.e., when :switch:`-gnatg` is used). 4593 4594 * A line consisting entirely of minus signs, possibly preceded by blanks, is 4595 permitted. This allows the construction of box comments where lines of minus 4596 signs are used to form the top and bottom of the box. 4597 4598 * A comment that starts and ends with ``--`` is permitted as long as at 4599 least one blank follows the initial ``--``. Together with the preceding 4600 rule, this allows the construction of box comments, as shown in the following 4601 example: 4602 4603 .. code-block:: ada 4604 4605 --------------------------- 4606 -- This is a box comment -- 4607 -- with two text lines. -- 4608 --------------------------- 4609 4610 4611.. index:: -gnatyC (gcc) 4612 4613:switch:`-gnatyC` 4614 *Check comments, single space.* 4615 4616 This is identical to ``c`` except that only one space 4617 is required following the ``--`` of a comment instead of two. 4618 4619 4620.. index:: -gnatyd (gcc) 4621 4622:switch:`-gnatyd` 4623 *Check no DOS line terminators present.* 4624 4625 All lines must be terminated by a single ASCII.LF 4626 character (in particular the DOS line terminator sequence CR/LF is not 4627 allowed). 4628 4629 4630.. index:: -gnatye (gcc) 4631 4632:switch:`-gnatye` 4633 *Check end/exit labels.* 4634 4635 Optional labels on ``end`` statements ending subprograms and on 4636 ``exit`` statements exiting named loops, are required to be present. 4637 4638 4639.. index:: -gnatyf (gcc) 4640 4641:switch:`-gnatyf` 4642 *No form feeds or vertical tabs.* 4643 4644 Neither form feeds nor vertical tab characters are permitted 4645 in the source text. 4646 4647 4648.. index:: -gnatyg (gcc) 4649 4650:switch:`-gnatyg` 4651 *GNAT style mode.* 4652 4653 The set of style check switches is set to match that used by the GNAT sources. 4654 This may be useful when developing code that is eventually intended to be 4655 incorporated into GNAT. Currently this is equivalent to :switch:`-gnatwydISux`) 4656 but additional style switches may be added to this set in the future without 4657 advance notice. 4658 4659 4660.. index:: -gnatyh (gcc) 4661 4662:switch:`-gnatyh` 4663 *No horizontal tabs.* 4664 4665 Horizontal tab characters are not permitted in the source text. 4666 Together with the b (no blanks at end of line) check, this 4667 enforces a canonical form for the use of blanks to separate 4668 source tokens. 4669 4670 4671.. index:: -gnatyi (gcc) 4672 4673:switch:`-gnatyi` 4674 *Check if-then layout.* 4675 4676 The keyword ``then`` must appear either on the same 4677 line as corresponding ``if``, or on a line on its own, lined 4678 up under the ``if``. 4679 4680 4681.. index:: -gnatyI (gcc) 4682 4683:switch:`-gnatyI` 4684 *check mode IN keywords.* 4685 4686 Mode ``in`` (the default mode) is not 4687 allowed to be given explicitly. ``in out`` is fine, 4688 but not ``in`` on its own. 4689 4690 4691.. index:: -gnatyk (gcc) 4692 4693:switch:`-gnatyk` 4694 *Check keyword casing.* 4695 4696 All keywords must be in lower case (with the exception of keywords 4697 such as ``digits`` used as attribute names to which this check 4698 does not apply). 4699 4700 4701.. index:: -gnatyl (gcc) 4702 4703:switch:`-gnatyl` 4704 *Check layout.* 4705 4706 Layout of statement and declaration constructs must follow the 4707 recommendations in the Ada Reference Manual, as indicated by the 4708 form of the syntax rules. For example an ``else`` keyword must 4709 be lined up with the corresponding ``if`` keyword. 4710 4711 There are two respects in which the style rule enforced by this check 4712 option are more liberal than those in the Ada Reference Manual. First 4713 in the case of record declarations, it is permissible to put the 4714 ``record`` keyword on the same line as the ``type`` keyword, and 4715 then the ``end`` in ``end record`` must line up under ``type``. 4716 This is also permitted when the type declaration is split on two lines. 4717 For example, any of the following three layouts is acceptable: 4718 4719 .. code-block:: ada 4720 4721 type q is record 4722 a : integer; 4723 b : integer; 4724 end record; 4725 4726 type q is 4727 record 4728 a : integer; 4729 b : integer; 4730 end record; 4731 4732 type q is 4733 record 4734 a : integer; 4735 b : integer; 4736 end record; 4737 4738 Second, in the case of a block statement, a permitted alternative 4739 is to put the block label on the same line as the ``declare`` or 4740 ``begin`` keyword, and then line the ``end`` keyword up under 4741 the block label. For example both the following are permitted: 4742 4743 .. code-block:: ada 4744 4745 Block : declare 4746 A : Integer := 3; 4747 begin 4748 Proc (A, A); 4749 end Block; 4750 4751 Block : 4752 declare 4753 A : Integer := 3; 4754 begin 4755 Proc (A, A); 4756 end Block; 4757 4758 The same alternative format is allowed for loops. For example, both of 4759 the following are permitted: 4760 4761 .. code-block:: ada 4762 4763 Clear : while J < 10 loop 4764 A (J) := 0; 4765 end loop Clear; 4766 4767 Clear : 4768 while J < 10 loop 4769 A (J) := 0; 4770 end loop Clear; 4771 4772 4773.. index:: -gnatyLnnn (gcc) 4774 4775:switch:`-gnatyL` 4776 *Set maximum nesting level.* 4777 4778 The maximum level of nesting of constructs (including subprograms, loops, 4779 blocks, packages, and conditionals) may not exceed the given value 4780 *nnn*. A value of zero disconnects this style check. 4781 4782 4783.. index:: -gnatym (gcc) 4784 4785:switch:`-gnatym` 4786 *Check maximum line length.* 4787 4788 The length of source lines must not exceed 79 characters, including 4789 any trailing blanks. The value of 79 allows convenient display on an 4790 80 character wide device or window, allowing for possible special 4791 treatment of 80 character lines. Note that this count is of 4792 characters in the source text. This means that a tab character counts 4793 as one character in this count and a wide character sequence counts as 4794 a single character (however many bytes are needed in the encoding). 4795 4796 4797.. index:: -gnatyMnnn (gcc) 4798 4799:switch:`-gnatyM` 4800 *Set maximum line length.* 4801 4802 The length of lines must not exceed the 4803 given value *nnn*. The maximum value that can be specified is 32767. 4804 If neither style option for setting the line length is used, then the 4805 default is 255. This also controls the maximum length of lexical elements, 4806 where the only restriction is that they must fit on a single line. 4807 4808 4809.. index:: -gnatyn (gcc) 4810 4811:switch:`-gnatyn` 4812 *Check casing of entities in Standard.* 4813 4814 Any identifier from Standard must be cased 4815 to match the presentation in the Ada Reference Manual (for example, 4816 ``Integer`` and ``ASCII.NUL``). 4817 4818 4819.. index:: -gnatyN (gcc) 4820 4821:switch:`-gnatyN` 4822 *Turn off all style checks.* 4823 4824 All style check options are turned off. 4825 4826 4827.. index:: -gnatyo (gcc) 4828 4829:switch:`-gnatyo` 4830 *Check order of subprogram bodies.* 4831 4832 All subprogram bodies in a given scope 4833 (e.g., a package body) must be in alphabetical order. The ordering 4834 rule uses normal Ada rules for comparing strings, ignoring casing 4835 of letters, except that if there is a trailing numeric suffix, then 4836 the value of this suffix is used in the ordering (e.g., Junk2 comes 4837 before Junk10). 4838 4839 4840.. index:: -gnatyO (gcc) 4841 4842:switch:`-gnatyO` 4843 *Check that overriding subprograms are explicitly marked as such.* 4844 4845 This applies to all subprograms of a derived type that override a primitive 4846 operation of the type, for both tagged and untagged types. In particular, 4847 the declaration of a primitive operation of a type extension that overrides 4848 an inherited operation must carry an overriding indicator. Another case is 4849 the declaration of a function that overrides a predefined operator (such 4850 as an equality operator). 4851 4852 4853.. index:: -gnatyp (gcc) 4854 4855:switch:`-gnatyp` 4856 *Check pragma casing.* 4857 4858 Pragma names must be written in mixed case, that is, the 4859 initial letter and any letter following an underscore must be uppercase. 4860 All other letters must be lowercase. An exception is that SPARK_Mode is 4861 allowed as an alternative for Spark_Mode. 4862 4863 4864.. index:: -gnatyr (gcc) 4865 4866:switch:`-gnatyr` 4867 *Check references.* 4868 4869 All identifier references must be cased in the same way as the 4870 corresponding declaration. No specific casing style is imposed on 4871 identifiers. The only requirement is for consistency of references 4872 with declarations. 4873 4874 4875.. index:: -gnatys (gcc) 4876 4877:switch:`-gnatys` 4878 *Check separate specs.* 4879 4880 Separate declarations ('specs') are required for subprograms (a 4881 body is not allowed to serve as its own declaration). The only 4882 exception is that parameterless library level procedures are 4883 not required to have a separate declaration. This exception covers 4884 the most frequent form of main program procedures. 4885 4886 4887.. index:: -gnatyS (gcc) 4888 4889:switch:`-gnatyS` 4890 *Check no statements after then/else.* 4891 4892 No statements are allowed 4893 on the same line as a ``then`` or ``else`` keyword following the 4894 keyword in an ``if`` statement. ``or else`` and ``and then`` are not 4895 affected, and a special exception allows a pragma to appear after ``else``. 4896 4897 4898.. index:: -gnatyt (gcc) 4899 4900:switch:`-gnatyt` 4901 *Check token spacing.* 4902 4903 The following token spacing rules are enforced: 4904 4905 * The keywords ``abs`` and ``not`` must be followed by a space. 4906 4907 * The token ``=>`` must be surrounded by spaces. 4908 4909 * The token ``<>`` must be preceded by a space or a left parenthesis. 4910 4911 * Binary operators other than ``**`` must be surrounded by spaces. 4912 There is no restriction on the layout of the ``**`` binary operator. 4913 4914 * Colon must be surrounded by spaces. 4915 4916 * Colon-equal (assignment, initialization) must be surrounded by spaces. 4917 4918 * Comma must be the first non-blank character on the line, or be 4919 immediately preceded by a non-blank character, and must be followed 4920 by a space. 4921 4922 * If the token preceding a left parenthesis ends with a letter or digit, then 4923 a space must separate the two tokens. 4924 4925 * If the token following a right parenthesis starts with a letter or digit, then 4926 a space must separate the two tokens. 4927 4928 * A right parenthesis must either be the first non-blank character on 4929 a line, or it must be preceded by a non-blank character. 4930 4931 * A semicolon must not be preceded by a space, and must not be followed by 4932 a non-blank character. 4933 4934 * A unary plus or minus may not be followed by a space. 4935 4936 * A vertical bar must be surrounded by spaces. 4937 4938 Exactly one blank (and no other white space) must appear between 4939 a ``not`` token and a following ``in`` token. 4940 4941 4942.. index:: -gnatyu (gcc) 4943 4944:switch:`-gnatyu` 4945 *Check unnecessary blank lines.* 4946 4947 Unnecessary blank lines are not allowed. A blank line is considered 4948 unnecessary if it appears at the end of the file, or if more than 4949 one blank line occurs in sequence. 4950 4951 4952.. index:: -gnatyx (gcc) 4953 4954:switch:`-gnatyx` 4955 *Check extra parentheses.* 4956 4957 Unnecessary extra level of parentheses (C-style) are not allowed 4958 around conditions in ``if`` statements, ``while`` statements and 4959 ``exit`` statements. 4960 4961 4962.. index:: -gnatyy (gcc) 4963 4964:switch:`-gnatyy` 4965 *Set all standard style check options.* 4966 4967 This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking 4968 options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`, 4969 :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`, 4970 :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`. 4971 4972 4973.. index:: -gnaty- (gcc) 4974 4975:switch:`-gnaty-` 4976 *Remove style check options.* 4977 4978 This causes any subsequent options in the string to act as canceling the 4979 corresponding style check option. To cancel maximum nesting level control, 4980 use the ``L`` parameter without any integer value after that, because any 4981 digit following *-* in the parameter string of the :switch:`-gnaty` 4982 option will be treated as canceling the indentation check. The same is true 4983 for the ``M`` parameter. ``y`` and ``N`` parameters are not 4984 allowed after *-*. 4985 4986 4987.. index:: -gnaty+ (gcc) 4988 4989:switch:`-gnaty+` 4990 *Enable style check options.* 4991 4992 This causes any subsequent options in the string to enable the corresponding 4993 style check option. That is, it cancels the effect of a previous -, 4994 if any. 4995 4996 4997.. end of switch description (leave this comment to ease automatic parsing for 4998.. GPS 4999 5000In the above rules, appearing in column one is always permitted, that is, 5001counts as meeting either a requirement for a required preceding space, 5002or as meeting a requirement for no preceding space. 5003 5004Appearing at the end of a line is also always permitted, that is, counts 5005as meeting either a requirement for a following space, or as meeting 5006a requirement for no following space. 5007 5008If any of these style rules is violated, a message is generated giving 5009details on the violation. The initial characters of such messages are 5010always '`(style)`'. Note that these messages are treated as warning 5011messages, so they normally do not prevent the generation of an object 5012file. The :switch:`-gnatwe` switch can be used to treat warning messages, 5013including style messages, as fatal errors. 5014 5015The switch :switch:`-gnaty` on its own (that is not 5016followed by any letters or digits) is equivalent 5017to the use of :switch:`-gnatyy` as described above, that is all 5018built-in standard style check options are enabled. 5019 5020The switch :switch:`-gnatyN` clears any previously set style checks. 5021 5022.. _Run-Time_Checks: 5023 5024Run-Time Checks 5025--------------- 5026 5027.. index:: Division by zero 5028 5029.. index:: Access before elaboration 5030 5031.. index:: Checks, division by zero 5032 5033.. index:: Checks, access before elaboration 5034 5035.. index:: Checks, stack overflow checking 5036 5037By default, the following checks are suppressed: stack overflow 5038checks, and checks for access before elaboration on subprogram 5039calls. All other checks, including overflow checks, range checks and 5040array bounds checks, are turned on by default. The following ``gcc`` 5041switches refine this default behavior. 5042 5043.. index:: -gnatp (gcc) 5044 5045:switch:`-gnatp` 5046 .. index:: Suppressing checks 5047 5048 .. index:: Checks, suppressing 5049 5050 This switch causes the unit to be compiled 5051 as though ``pragma Suppress (All_checks)`` 5052 had been present in the source. Validity checks are also eliminated (in 5053 other words :switch:`-gnatp` also implies :switch:`-gnatVn`. 5054 Use this switch to improve the performance 5055 of the code at the expense of safety in the presence of invalid data or 5056 program bugs. 5057 5058 Note that when checks are suppressed, the compiler is allowed, but not 5059 required, to omit the checking code. If the run-time cost of the 5060 checking code is zero or near-zero, the compiler will generate it even 5061 if checks are suppressed. In particular, if the compiler can prove 5062 that a certain check will necessarily fail, it will generate code to 5063 do an unconditional 'raise', even if checks are suppressed. The 5064 compiler warns in this case. Another case in which checks may not be 5065 eliminated is when they are embedded in certain run time routines such 5066 as math library routines. 5067 5068 Of course, run-time checks are omitted whenever the compiler can prove 5069 that they will not fail, whether or not checks are suppressed. 5070 5071 Note that if you suppress a check that would have failed, program 5072 execution is erroneous, which means the behavior is totally 5073 unpredictable. The program might crash, or print wrong answers, or 5074 do anything else. It might even do exactly what you wanted it to do 5075 (and then it might start failing mysteriously next week or next 5076 year). The compiler will generate code based on the assumption that 5077 the condition being checked is true, which can result in erroneous 5078 execution if that assumption is wrong. 5079 5080 The checks subject to suppression include all the checks defined by the Ada 5081 standard, the additional implementation defined checks ``Alignment_Check``, 5082 ``Duplicated_Tag_Check``, ``Predicate_Check``, ``Container_Checks``, ``Tampering_Check``, 5083 and ``Validity_Check``, as well as any checks introduced using ``pragma Check_Name``. 5084 Note that ``Atomic_Synchronization`` is not automatically suppressed by use of this option. 5085 5086 If the code depends on certain checks being active, you can use 5087 pragma ``Unsuppress`` either as a configuration pragma or as 5088 a local pragma to make sure that a specified check is performed 5089 even if ``gnatp`` is specified. 5090 5091 The :switch:`-gnatp` switch has no effect if a subsequent 5092 :switch:`-gnat-p` switch appears. 5093 5094 5095.. index:: -gnat-p (gcc) 5096.. index:: Suppressing checks 5097.. index:: Checks, suppressing 5098.. index:: Suppress 5099 5100:switch:`-gnat-p` 5101 This switch cancels the effect of a previous ``gnatp`` switch. 5102 5103 5104.. index:: -gnato?? (gcc) 5105.. index:: Overflow checks 5106.. index:: Overflow mode 5107.. index:: Check, overflow 5108 5109:switch:`-gnato??` 5110 This switch controls the mode used for computing intermediate 5111 arithmetic integer operations, and also enables overflow checking. 5112 For a full description of overflow mode and checking control, see 5113 the 'Overflow Check Handling in GNAT' appendix in this 5114 User's Guide. 5115 5116 Overflow checks are always enabled by this switch. The argument 5117 controls the mode, using the codes 5118 5119 5120 *1 = STRICT* 5121 In STRICT mode, intermediate operations are always done using the 5122 base type, and overflow checking ensures that the result is within 5123 the base type range. 5124 5125 5126 *2 = MINIMIZED* 5127 In MINIMIZED mode, overflows in intermediate operations are avoided 5128 where possible by using a larger integer type for the computation 5129 (typically ``Long_Long_Integer``). Overflow checking ensures that 5130 the result fits in this larger integer type. 5131 5132 5133 *3 = ELIMINATED* 5134 In ELIMINATED mode, overflows in intermediate operations are avoided 5135 by using multi-precision arithmetic. In this case, overflow checking 5136 has no effect on intermediate operations (since overflow is impossible). 5137 5138 If two digits are present after :switch:`-gnato` then the first digit 5139 sets the mode for expressions outside assertions, and the second digit 5140 sets the mode for expressions within assertions. Here assertions is used 5141 in the technical sense (which includes for example precondition and 5142 postcondition expressions). 5143 5144 If one digit is present, the corresponding mode is applicable to both 5145 expressions within and outside assertion expressions. 5146 5147 If no digits are present, the default is to enable overflow checks 5148 and set STRICT mode for both kinds of expressions. This is compatible 5149 with the use of :switch:`-gnato` in previous versions of GNAT. 5150 5151 .. index:: Machine_Overflows 5152 5153 Note that the :switch:`-gnato??` switch does not affect the code generated 5154 for any floating-point operations; it applies only to integer semantics. 5155 For floating-point, GNAT has the ``Machine_Overflows`` 5156 attribute set to ``False`` and the normal mode of operation is to 5157 generate IEEE NaN and infinite values on overflow or invalid operations 5158 (such as dividing 0.0 by 0.0). 5159 5160 The reason that we distinguish overflow checking from other kinds of 5161 range constraint checking is that a failure of an overflow check, unlike 5162 for example the failure of a range check, can result in an incorrect 5163 value, but cannot cause random memory destruction (like an out of range 5164 subscript), or a wild jump (from an out of range case value). Overflow 5165 checking is also quite expensive in time and space, since in general it 5166 requires the use of double length arithmetic. 5167 5168 Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`), 5169 so overflow checking is performed in STRICT mode by default. 5170 5171 5172.. index:: -gnatE (gcc) 5173.. index:: Elaboration checks 5174.. index:: Check, elaboration 5175 5176:switch:`-gnatE` 5177 Enables dynamic checks for access-before-elaboration 5178 on subprogram calls and generic instantiations. 5179 Note that :switch:`-gnatE` is not necessary for safety, because in the 5180 default mode, GNAT ensures statically that the checks would not fail. 5181 For full details of the effect and use of this switch, 5182 :ref:`Compiling_with_gcc`. 5183 5184 5185.. index:: -fstack-check (gcc) 5186.. index:: Stack Overflow Checking 5187.. index:: Checks, stack overflow checking 5188 5189:switch:`-fstack-check` 5190 Activates stack overflow checking. For full details of the effect and use of 5191 this switch see :ref:`Stack_Overflow_Checking`. 5192 5193.. index:: Unsuppress 5194 5195The setting of these switches only controls the default setting of the 5196checks. You may modify them using either ``Suppress`` (to remove 5197checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in 5198the program source. 5199 5200 5201.. _Using_gcc_for_Syntax_Checking: 5202 5203Using ``gcc`` for Syntax Checking 5204--------------------------------- 5205 5206.. index:: -gnats (gcc) 5207 5208:switch:`-gnats` 5209 The ``s`` stands for 'syntax'. 5210 5211 Run GNAT in syntax checking only mode. For 5212 example, the command 5213 5214 :: 5215 5216 $ gcc -c -gnats x.adb 5217 5218 compiles file :file:`x.adb` in syntax-check-only mode. You can check a 5219 series of files in a single command 5220 , and can use wild cards to specify such a group of files. 5221 Note that you must specify the :switch:`-c` (compile 5222 only) flag in addition to the :switch:`-gnats` flag. 5223 5224 You may use other switches in conjunction with :switch:`-gnats`. In 5225 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the 5226 format of any generated error messages. 5227 5228 When the source file is empty or contains only empty lines and/or comments, 5229 the output is a warning: 5230 5231 5232 :: 5233 5234 $ gcc -c -gnats -x ada toto.txt 5235 toto.txt:1:01: warning: empty file, contains no compilation units 5236 $ 5237 5238 5239 Otherwise, the output is simply the error messages, if any. No object file or 5240 ALI file is generated by a syntax-only compilation. Also, no units other 5241 than the one specified are accessed. For example, if a unit ``X`` 5242 |withs| a unit ``Y``, compiling unit ``X`` in syntax 5243 check only mode does not access the source file containing unit 5244 ``Y``. 5245 5246 .. index:: Multiple units, syntax checking 5247 5248 Normally, GNAT allows only a single unit in a source file. However, this 5249 restriction does not apply in syntax-check-only mode, and it is possible 5250 to check a file containing multiple compilation units concatenated 5251 together. This is primarily used by the ``gnatchop`` utility 5252 (:ref:`Renaming_Files_with_gnatchop`). 5253 5254.. _Using_gcc_for_Semantic_Checking: 5255 5256Using ``gcc`` for Semantic Checking 5257----------------------------------- 5258 5259 5260 5261.. index:: -gnatc (gcc) 5262 5263:switch:`-gnatc` 5264 The ``c`` stands for 'check'. 5265 Causes the compiler to operate in semantic check mode, 5266 with full checking for all illegalities specified in the 5267 Ada Reference Manual, but without generation of any object code 5268 (no object file is generated). 5269 5270 Because dependent files must be accessed, you must follow the GNAT 5271 semantic restrictions on file structuring to operate in this mode: 5272 5273 * The needed source files must be accessible 5274 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). 5275 5276 * Each file must contain only one compilation unit. 5277 5278 * The file name and unit name must match (:ref:`File_Naming_Rules`). 5279 5280 The output consists of error messages as appropriate. No object file is 5281 generated. An :file:`ALI` file is generated for use in the context of 5282 cross-reference tools, but this file is marked as not being suitable 5283 for binding (since no object file is generated). 5284 The checking corresponds exactly to the notion of 5285 legality in the Ada Reference Manual. 5286 5287 Any unit can be compiled in semantics-checking-only mode, including 5288 units that would not normally be compiled (subunits, 5289 and specifications where a separate body is present). 5290 5291.. _Compiling_Different_Versions_of_Ada: 5292 5293Compiling Different Versions of Ada 5294----------------------------------- 5295 5296The switches described in this section allow you to explicitly specify 5297the version of the Ada language that your programs are written in. 5298The default mode is Ada 2012, 5299but you can also specify Ada 95, Ada 2005 mode, or 5300indicate Ada 83 compatibility mode. 5301 5302 5303.. index:: Compatibility with Ada 83 5304.. index:: -gnat83 (gcc) 5305.. index:: ACVC, Ada 83 tests 5306.. index:: Ada 83 mode 5307 5308:switch:`-gnat83` (Ada 83 Compatibility Mode) 5309 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch 5310 specifies that the program is to be compiled in Ada 83 mode. With 5311 :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83 5312 semantics where this can be done easily. 5313 It is not possible to guarantee this switch does a perfect 5314 job; some subtle tests, such as are 5315 found in earlier ACVC tests (and that have been removed from the ACATS suite 5316 for Ada 95), might not compile correctly. 5317 Nevertheless, this switch may be useful in some circumstances, for example 5318 where, due to contractual reasons, existing code needs to be maintained 5319 using only Ada 83 features. 5320 5321 With few exceptions (most notably the need to use ``<>`` on 5322 unconstrained :index:`generic formal parameters <Generic formal parameters>`, 5323 the use of the new Ada 95 / Ada 2005 5324 reserved words, and the use of packages 5325 with optional bodies), it is not necessary to specify the 5326 :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare 5327 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus 5328 a correct Ada 83 program is usually also a correct program 5329 in these later versions of the language standard. For further information 5330 please refer to the *Compatibility and Porting Guide* chapter in the 5331 :title:`GNAT Reference Manual`. 5332 5333 5334.. index:: -gnat95 (gcc) 5335.. index:: Ada 95 mode 5336 5337:switch:`-gnat95` (Ada 95 mode) 5338 This switch directs the compiler to implement the Ada 95 version of the 5339 language. 5340 Since Ada 95 is almost completely upwards 5341 compatible with Ada 83, Ada 83 programs may generally be compiled using 5342 this switch (see the description of the :switch:`-gnat83` switch for further 5343 information about Ada 83 mode). 5344 If an Ada 2005 program is compiled in Ada 95 mode, 5345 uses of the new Ada 2005 features will cause error 5346 messages or warnings. 5347 5348 This switch also can be used to cancel the effect of a previous 5349 :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012` 5350 switch earlier in the command line. 5351 5352 5353.. index:: -gnat05 (gcc) 5354.. index:: -gnat2005 (gcc) 5355.. index:: Ada 2005 mode 5356 5357:switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode) 5358 This switch directs the compiler to implement the Ada 2005 version of the 5359 language, as documented in the official Ada standards document. 5360 Since Ada 2005 is almost completely upwards 5361 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs 5362 may generally be compiled using this switch (see the description of the 5363 :switch:`-gnat83` and :switch:`-gnat95` switches for further 5364 information). 5365 5366 5367.. index:: -gnat12 (gcc) 5368.. index:: -gnat2012 (gcc) 5369.. index:: Ada 2012 mode 5370 5371:switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode) 5372 This switch directs the compiler to implement the Ada 2012 version of the 5373 language (also the default). 5374 Since Ada 2012 is almost completely upwards 5375 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), 5376 Ada 83 and Ada 95 programs 5377 may generally be compiled using this switch (see the description of the 5378 :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches 5379 for further information). 5380 5381 5382.. index:: -gnatX (gcc) 5383.. index:: Ada language extensions 5384.. index:: GNAT extensions 5385 5386:switch:`-gnatX` (Enable GNAT Extensions) 5387 This switch directs the compiler to implement the latest version of the 5388 language (currently Ada 2012) and also to enable certain GNAT implementation 5389 extensions that are not part of any Ada standard. For a full list of these 5390 extensions, see the GNAT reference manual. 5391 5392 5393.. _Character_Set_Control: 5394 5395Character Set Control 5396--------------------- 5397 5398.. index:: -gnati (gcc) 5399 5400:switch:`-gnati{c}` 5401 Normally GNAT recognizes the Latin-1 character set in source program 5402 identifiers, as described in the Ada Reference Manual. 5403 This switch causes 5404 GNAT to recognize alternate character sets in identifiers. ``c`` is a 5405 single character indicating the character set, as follows: 5406 5407 ========== ====================================================== 5408 *1* ISO 8859-1 (Latin-1) identifiers 5409 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers 5410 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers 5411 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers 5412 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers 5413 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers 5414 *p* IBM PC letters (code page 437) allowed in identifiers 5415 *8* IBM PC letters (code page 850) allowed in identifiers 5416 *f* Full upper-half codes allowed in identifiers 5417 *n* No upper-half codes allowed in identifiers 5418 *w* Wide-character codes (that is, codes greater than 255) 5419 allowed in identifiers 5420 ========== ====================================================== 5421 5422 See :ref:`Foreign_Language_Representation` for full details on the 5423 implementation of these character sets. 5424 5425 5426.. index:: -gnatW (gcc) 5427 5428:switch:`-gnatW{e}` 5429 Specify the method of encoding for wide characters. 5430 ``e`` is one of the following: 5431 5432 ========== ====================================================== 5433 *h* Hex encoding (brackets coding also recognized) 5434 *u* Upper half encoding (brackets encoding also recognized) 5435 *s* Shift/JIS encoding (brackets encoding also recognized) 5436 *e* EUC encoding (brackets encoding also recognized) 5437 *8* UTF-8 encoding (brackets encoding also recognized) 5438 *b* Brackets encoding only (default value) 5439 ========== ====================================================== 5440 5441 For full details on these encoding 5442 methods see :ref:`Wide_Character_Encodings`. 5443 Note that brackets coding is always accepted, even if one of the other 5444 options is specified, so for example :switch:`-gnatW8` specifies that both 5445 brackets and UTF-8 encodings will be recognized. The units that are 5446 with'ed directly or indirectly will be scanned using the specified 5447 representation scheme, and so if one of the non-brackets scheme is 5448 used, it must be used consistently throughout the program. However, 5449 since brackets encoding is always recognized, it may be conveniently 5450 used in standard libraries, allowing these libraries to be used with 5451 any of the available coding schemes. 5452 5453 Note that brackets encoding only applies to program text. Within comments, 5454 brackets are considered to be normal graphic characters, and bracket sequences 5455 are never recognized as wide characters. 5456 5457 If no :switch:`-gnatW?` parameter is present, then the default 5458 representation is normally Brackets encoding only. However, if the 5459 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard 5460 byte order mark or BOM for UTF-8), then these three characters are 5461 skipped and the default representation for the file is set to UTF-8. 5462 5463 Note that the wide character representation that is specified (explicitly 5464 or by default) for the main program also acts as the default encoding used 5465 for Wide_Text_IO files if not specifically overridden by a WCEM form 5466 parameter. 5467 5468 5469When no :switch:`-gnatW?` is specified, then characters (other than wide 5470characters represented using brackets notation) are treated as 8-bit 5471Latin-1 codes. The codes recognized are the Latin-1 graphic characters, 5472and ASCII format effectors (CR, LF, HT, VT). Other lower half control 5473characters in the range 16#00#..16#1F# are not accepted in program text 5474or in comments. Upper half control characters (16#80#..16#9F#) are rejected 5475in program text, but allowed and ignored in comments. Note in particular 5476that the Next Line (NEL) character whose encoding is 16#85# is not recognized 5477as an end of line in this default mode. If your source program contains 5478instances of the NEL character used as a line terminator, 5479you must use UTF-8 encoding for the whole 5480source program. In default mode, all lines must be ended by a standard 5481end of line sequence (CR, CR/LF, or LF). 5482 5483Note that the convention of simply accepting all upper half characters in 5484comments means that programs that use standard ASCII for program text, but 5485UTF-8 encoding for comments are accepted in default mode, providing that the 5486comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator. 5487This is a common mode for many programs with foreign language comments. 5488 5489.. _File_Naming_Control: 5490 5491File Naming Control 5492------------------- 5493 5494.. index:: -gnatk (gcc) 5495 5496:switch:`-gnatk{n}` 5497 Activates file name 'krunching'. ``n``, a decimal integer in the range 5498 1-999, indicates the maximum allowable length of a file name (not 5499 including the :file:`.ads` or :file:`.adb` extension). The default is not 5500 to enable file name krunching. 5501 5502 For the source file naming rules, :ref:`File_Naming_Rules`. 5503 5504.. _Subprogram_Inlining_Control: 5505 5506Subprogram Inlining Control 5507--------------------------- 5508 5509.. index:: -gnatn (gcc) 5510 5511:switch:`-gnatn[12]` 5512 The ``n`` here is intended to suggest the first syllable of the word 'inline'. 5513 GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to 5514 actually occur, optimization must be enabled and, by default, inlining of 5515 subprograms across modules is not performed. If you want to additionally 5516 enable inlining of subprograms specified by pragma ``Inline`` across modules, 5517 you must also specify this switch. 5518 5519 In the absence of this switch, GNAT does not attempt inlining across modules 5520 and does not access the bodies of subprograms for which ``pragma Inline`` is 5521 specified if they are not in the current unit. 5522 5523 You can optionally specify the inlining level: 1 for moderate inlining across 5524 modules, which is a good compromise between compilation times and performances 5525 at run time, or 2 for full inlining across modules, which may bring about 5526 longer compilation times. If no inlining level is specified, the compiler will 5527 pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or 5528 :switch:`-Os` and 2 for :switch:`-O3`. 5529 5530 If you specify this switch the compiler will access these bodies, 5531 creating an extra source dependency for the resulting object file, and 5532 where possible, the call will be inlined. 5533 For further details on when inlining is possible 5534 see :ref:`Inlining_of_Subprograms`. 5535 5536 5537.. index:: -gnatN (gcc) 5538 5539:switch:`-gnatN` 5540 This switch activates front-end inlining which also 5541 generates additional dependencies. 5542 5543 When using a gcc-based back end (in practice this means using any version 5544 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of 5545 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred. 5546 Historically front end inlining was more extensive than the gcc back end 5547 inlining, but that is no longer the case. 5548 5549.. _Auxiliary_Output_Control: 5550 5551Auxiliary Output Control 5552------------------------ 5553 5554.. index:: -gnatt (gcc) 5555.. index:: Writing internal trees 5556.. index:: Internal trees, writing to file 5557 5558:switch:`-gnatt` 5559 Causes GNAT to write the internal tree for a unit to a file (with the 5560 extension :file:`.adt`. 5561 This not normally required, but is used by separate analysis tools. 5562 Typically 5563 these tools do the necessary compilations automatically, so you should 5564 not have to specify this switch in normal operation. 5565 Note that the combination of switches :switch:`-gnatct` 5566 generates a tree in the form required by ASIS applications. 5567 5568 5569.. index:: -gnatu (gcc) 5570 5571:switch:`-gnatu` 5572 Print a list of units required by this compilation on :file:`stdout`. 5573 The listing includes all units on which the unit being compiled depends 5574 either directly or indirectly. 5575 5576 5577.. index:: -pass-exit-codes (gcc) 5578 5579:switch:`-pass-exit-codes` 5580 If this switch is not used, the exit code returned by ``gcc`` when 5581 compiling multiple files indicates whether all source files have 5582 been successfully used to generate object files or not. 5583 5584 When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended 5585 exit status and allows an integrated development environment to better 5586 react to a compilation failure. Those exit status are: 5587 5588 ========== ====================================================== 5589 *5* There was an error in at least one source file. 5590 *3* At least one source file did not generate an object file. 5591 *2* The compiler died unexpectedly (internal error for example). 5592 *0* An object file has been generated for every source file. 5593 ========== ====================================================== 5594 5595.. _Debugging_Control: 5596 5597Debugging Control 5598----------------- 5599 5600 .. index:: Debugging options 5601 5602 5603.. index:: -gnatd (gcc) 5604 5605:switch:`-gnatd{x}` 5606 Activate internal debugging switches. ``x`` is a letter or digit, or 5607 string of letters or digits, which specifies the type of debugging 5608 outputs desired. Normally these are used only for internal development 5609 or system debugging purposes. You can find full documentation for these 5610 switches in the body of the ``Debug`` unit in the compiler source 5611 file :file:`debug.adb`. 5612 5613 5614.. index:: -gnatG (gcc) 5615 5616:switch:`-gnatG[={nn}]` 5617 This switch causes the compiler to generate auxiliary output containing 5618 a pseudo-source listing of the generated expanded code. Like most Ada 5619 compilers, GNAT works by first transforming the high level Ada code into 5620 lower level constructs. For example, tasking operations are transformed 5621 into calls to the tasking run-time routines. A unique capability of GNAT 5622 is to list this expanded code in a form very close to normal Ada source. 5623 This is very useful in understanding the implications of various Ada 5624 usage on the efficiency of the generated code. There are many cases in 5625 Ada (e.g., the use of controlled types), where simple Ada statements can 5626 generate a lot of run-time code. By using :switch:`-gnatG` you can identify 5627 these cases, and consider whether it may be desirable to modify the coding 5628 approach to improve efficiency. 5629 5630 The optional parameter ``nn`` if present after -gnatG specifies an 5631 alternative maximum line length that overrides the normal default of 72. 5632 This value is in the range 40-999999, values less than 40 being silently 5633 reset to 40. The equal sign is optional. 5634 5635 The format of the output is very similar to standard Ada source, and is 5636 easily understood by an Ada programmer. The following special syntactic 5637 additions correspond to low level features used in the generated code that 5638 do not have any exact analogies in pure Ada source form. The following 5639 is a partial list of these special constructions. See the spec 5640 of package ``Sprint`` in file :file:`sprint.ads` for a full list. 5641 5642 .. index:: -gnatL (gcc) 5643 5644 If the switch :switch:`-gnatL` is used in conjunction with 5645 :switch:`-gnatG`, then the original source lines are interspersed 5646 in the expanded source (as comment lines with the original line number). 5647 5648 :samp:`new {xxx} [storage_pool = {yyy}]` 5649 Shows the storage pool being used for an allocator. 5650 5651 5652 :samp:`at end {procedure-name};` 5653 Shows the finalization (cleanup) procedure for a scope. 5654 5655 5656 :samp:`(if {expr} then {expr} else {expr})` 5657 Conditional expression equivalent to the ``x?y:z`` construction in C. 5658 5659 5660 :samp:`{target}^({source})` 5661 A conversion with floating-point truncation instead of rounding. 5662 5663 5664 :samp:`{target}?({source})` 5665 A conversion that bypasses normal Ada semantic checking. In particular 5666 enumeration types and fixed-point types are treated simply as integers. 5667 5668 5669 :samp:`{target}?^({source})` 5670 Combines the above two cases. 5671 5672 5673 :samp:`{x} #/ {y}` 5674 5675 :samp:`{x} #mod {y}` 5676 5677 :samp:`{x} # {y}` 5678 5679 :samp:`{x} #rem {y}` 5680 A division or multiplication of fixed-point values which are treated as 5681 integers without any kind of scaling. 5682 5683 5684 :samp:`free {expr} [storage_pool = {xxx}]` 5685 Shows the storage pool associated with a ``free`` statement. 5686 5687 5688 :samp:`[subtype or type declaration]` 5689 Used to list an equivalent declaration for an internally generated 5690 type that is referenced elsewhere in the listing. 5691 5692 5693 :samp:`freeze {type-name} [{actions}]` 5694 Shows the point at which ``type-name`` is frozen, with possible 5695 associated actions to be performed at the freeze point. 5696 5697 5698 :samp:`reference {itype}` 5699 Reference (and hence definition) to internal type ``itype``. 5700 5701 5702 :samp:`{function-name}! ({arg}, {arg}, {arg})` 5703 Intrinsic function call. 5704 5705 5706 :samp:`{label-name} : label` 5707 Declaration of label ``labelname``. 5708 5709 5710 :samp:`#$ {subprogram-name}` 5711 An implicit call to a run-time support routine 5712 (to meet the requirement of H.3.1(9) in a 5713 convenient manner). 5714 5715 5716 :samp:`{expr} && {expr} && {expr} ... && {expr}` 5717 A multiple concatenation (same effect as ``expr`` & ``expr`` & 5718 ``expr``, but handled more efficiently). 5719 5720 5721 :samp:`[constraint_error]` 5722 Raise the ``Constraint_Error`` exception. 5723 5724 5725 :samp:`{expression}'reference` 5726 A pointer to the result of evaluating {expression}. 5727 5728 5729 :samp:`{target-type}!({source-expression})` 5730 An unchecked conversion of ``source-expression`` to ``target-type``. 5731 5732 5733 :samp:`[{numerator}/{denominator}]` 5734 Used to represent internal real literals (that) have no exact 5735 representation in base 2-16 (for example, the result of compile time 5736 evaluation of the expression 1.0/27.0). 5737 5738 5739.. index:: -gnatD (gcc) 5740 5741:switch:`-gnatD[=nn]` 5742 When used in conjunction with :switch:`-gnatG`, this switch causes 5743 the expanded source, as described above for 5744 :switch:`-gnatG` to be written to files with names 5745 :file:`xxx.dg`, where :file:`xxx` is the normal file name, 5746 instead of to the standard output file. For 5747 example, if the source file name is :file:`hello.adb`, then a file 5748 :file:`hello.adb.dg` will be written. The debugging 5749 information generated by the ``gcc`` :switch:`-g` switch 5750 will refer to the generated :file:`xxx.dg` file. This allows 5751 you to do source level debugging using the generated code which is 5752 sometimes useful for complex code, for example to find out exactly 5753 which part of a complex construction raised an exception. This switch 5754 also suppresses generation of cross-reference information (see 5755 :switch:`-gnatx`) since otherwise the cross-reference information 5756 would refer to the :file:`.dg` file, which would cause 5757 confusion since this is not the original source file. 5758 5759 Note that :switch:`-gnatD` actually implies :switch:`-gnatG` 5760 automatically, so it is not necessary to give both options. 5761 In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`). 5762 5763 .. index:: -gnatL (gcc) 5764 5765 If the switch :switch:`-gnatL` is used in conjunction with 5766 :switch:`-gnatDG`, then the original source lines are interspersed 5767 in the expanded source (as comment lines with the original line number). 5768 5769 The optional parameter ``nn`` if present after -gnatD specifies an 5770 alternative maximum line length that overrides the normal default of 72. 5771 This value is in the range 40-999999, values less than 40 being silently 5772 reset to 40. The equal sign is optional. 5773 5774 5775.. index:: -gnatr (gcc) 5776.. index:: pragma Restrictions 5777 5778:switch:`-gnatr` 5779 This switch causes pragma Restrictions to be treated as Restriction_Warnings 5780 so that violation of restrictions causes warnings rather than illegalities. 5781 This is useful during the development process when new restrictions are added 5782 or investigated. The switch also causes pragma Profile to be treated as 5783 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set 5784 restriction warnings rather than restrictions. 5785 5786 5787.. index:: -gnatR (gcc) 5788 5789:switch:`-gnatR[0|1|2|3][e][m][s]` 5790 This switch controls output from the compiler of a listing showing 5791 representation information for declared types, objects and subprograms. 5792 For :switch:`-gnatR0`, no information is output (equivalent to omitting 5793 the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default, 5794 so :switch:`-gnatR` with no parameter has the same effect), size and 5795 alignment information is listed for declared array and record types. 5796 For :switch:`-gnatR2`, size and alignment information is listed for all 5797 declared types and objects. The ``Linker_Section`` is also listed for any 5798 entity for which the ``Linker_Section`` is set explicitly or implicitly (the 5799 latter case occurs for objects of a type for which a ``Linker_Section`` 5800 is set). 5801 5802 For :switch:`-gnatR3`, symbolic expressions for values that are computed 5803 at run time for records are included. These symbolic expressions have 5804 a mostly obvious format with #n being used to represent the value of the 5805 n'th discriminant. See source files :file:`repinfo.ads/adb` in the 5806 GNAT sources for full details on the format of :switch:`-gnatR3` output. 5807 5808 If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then 5809 extended representation information for record sub-components of records 5810 are included. 5811 5812 If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then 5813 subprogram conventions and parameter passing mechanisms for all the 5814 subprograms are included. 5815 5816 If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then 5817 the output is to a file with the name :file:`file.rep` where file is 5818 the name of the corresponding source file. 5819 5820 Note that it is possible for record components to have zero size. In 5821 this case, the component clause uses an obvious extension of permitted 5822 Ada syntax, for example ``at 0 range 0 .. -1``. 5823 5824 5825.. index:: -gnatS (gcc) 5826 5827:switch:`-gnatS` 5828 The use of the switch :switch:`-gnatS` for an 5829 Ada compilation will cause the compiler to output a 5830 representation of package Standard in a form very 5831 close to standard Ada. It is not quite possible to 5832 do this entirely in standard Ada (since new 5833 numeric base types cannot be created in standard 5834 Ada), but the output is easily 5835 readable to any Ada programmer, and is useful to 5836 determine the characteristics of target dependent 5837 types in package Standard. 5838 5839 5840.. index:: -gnatx (gcc) 5841 5842:switch:`-gnatx` 5843 Normally the compiler generates full cross-referencing information in 5844 the :file:`ALI` file. This information is used by a number of tools, 5845 including ``gnatfind`` and ``gnatxref``. The :switch:`-gnatx` switch 5846 suppresses this information. This saves some space and may slightly 5847 speed up compilation, but means that these tools cannot be used. 5848 5849.. _Exception_Handling_Control: 5850 5851Exception Handling Control 5852-------------------------- 5853 5854GNAT uses two methods for handling exceptions at run-time. The 5855``setjmp/longjmp`` method saves the context when entering 5856a frame with an exception handler. Then when an exception is 5857raised, the context can be restored immediately, without the 5858need for tracing stack frames. This method provides very fast 5859exception propagation, but introduces significant overhead for 5860the use of exception handlers, even if no exception is raised. 5861 5862The other approach is called 'zero cost' exception handling. 5863With this method, the compiler builds static tables to describe 5864the exception ranges. No dynamic code is required when entering 5865a frame containing an exception handler. When an exception is 5866raised, the tables are used to control a back trace of the 5867subprogram invocation stack to locate the required exception 5868handler. This method has considerably poorer performance for 5869the propagation of exceptions, but there is no overhead for 5870exception handlers if no exception is raised. Note that in this 5871mode and in the context of mixed Ada and C/C++ programming, 5872to propagate an exception through a C/C++ code, the C/C++ code 5873must be compiled with the :switch:`-funwind-tables` GCC's 5874option. 5875 5876The following switches may be used to control which of the 5877two exception handling methods is used. 5878 5879 5880 5881.. index:: --RTS=sjlj (gnatmake) 5882 5883:switch:`--RTS=sjlj` 5884 This switch causes the setjmp/longjmp run-time (when available) to be used 5885 for exception handling. If the default 5886 mechanism for the target is zero cost exceptions, then 5887 this switch can be used to modify this default, and must be 5888 used for all units in the partition. 5889 This option is rarely used. One case in which it may be 5890 advantageous is if you have an application where exception 5891 raising is common and the overall performance of the 5892 application is improved by favoring exception propagation. 5893 5894 5895.. index:: --RTS=zcx (gnatmake) 5896.. index:: Zero Cost Exceptions 5897 5898:switch:`--RTS=zcx` 5899 This switch causes the zero cost approach to be used 5900 for exception handling. If this is the default mechanism for the 5901 target (see below), then this switch is unneeded. If the default 5902 mechanism for the target is setjmp/longjmp exceptions, then 5903 this switch can be used to modify this default, and must be 5904 used for all units in the partition. 5905 This option can only be used if the zero cost approach 5906 is available for the target in use, otherwise it will generate an error. 5907 5908The same option :switch:`--RTS` must be used both for ``gcc`` 5909and ``gnatbind``. Passing this option to ``gnatmake`` 5910(:ref:`Switches_for_gnatmake`) will ensure the required consistency 5911through the compilation and binding steps. 5912 5913.. _Units_to_Sources_Mapping_Files: 5914 5915Units to Sources Mapping Files 5916------------------------------ 5917 5918 5919 5920.. index:: -gnatem (gcc) 5921 5922:switch:`-gnatem={path}` 5923 A mapping file is a way to communicate to the compiler two mappings: 5924 from unit names to file names (without any directory information) and from 5925 file names to path names (with full directory information). These mappings 5926 are used by the compiler to short-circuit the path search. 5927 5928 The use of mapping files is not required for correct operation of the 5929 compiler, but mapping files can improve efficiency, particularly when 5930 sources are read over a slow network connection. In normal operation, 5931 you need not be concerned with the format or use of mapping files, 5932 and the :switch:`-gnatem` switch is not a switch that you would use 5933 explicitly. It is intended primarily for use by automatic tools such as 5934 ``gnatmake`` running under the project file facility. The 5935 description here of the format of mapping files is provided 5936 for completeness and for possible use by other tools. 5937 5938 A mapping file is a sequence of sets of three lines. In each set, the 5939 first line is the unit name, in lower case, with ``%s`` appended 5940 for specs and ``%b`` appended for bodies; the second line is the 5941 file name; and the third line is the path name. 5942 5943 Example:: 5944 5945 main%b 5946 main.2.ada 5947 /gnat/project1/sources/main.2.ada 5948 5949 5950 When the switch :switch:`-gnatem` is specified, the compiler will 5951 create in memory the two mappings from the specified file. If there is 5952 any problem (nonexistent file, truncated file or duplicate entries), 5953 no mapping will be created. 5954 5955 Several :switch:`-gnatem` switches may be specified; however, only the 5956 last one on the command line will be taken into account. 5957 5958 When using a project file, ``gnatmake`` creates a temporary 5959 mapping file and communicates it to the compiler using this switch. 5960 5961 5962.. _Code_Generation_Control: 5963 5964Code Generation Control 5965----------------------- 5966 5967The GCC technology provides a wide range of target dependent 5968:switch:`-m` switches for controlling 5969details of code generation with respect to different versions of 5970architectures. This includes variations in instruction sets (e.g., 5971different members of the power pc family), and different requirements 5972for optimal arrangement of instructions (e.g., different members of 5973the x86 family). The list of available :switch:`-m` switches may be 5974found in the GCC documentation. 5975 5976Use of these :switch:`-m` switches may in some cases result in improved 5977code performance. 5978 5979The GNAT technology is tested and qualified without any 5980:switch:`-m` switches, 5981so generally the most reliable approach is to avoid the use of these 5982switches. However, we generally expect most of these switches to work 5983successfully with GNAT, and many customers have reported successful 5984use of these options. 5985 5986Our general advice is to avoid the use of :switch:`-m` switches unless 5987special needs lead to requirements in this area. In particular, 5988there is no point in using :switch:`-m` switches to improve performance 5989unless you actually see a performance improvement. 5990 5991 5992.. _Linker_Switches: 5993 5994Linker Switches 5995=============== 5996 5997Linker switches can be specified after :switch:`-largs` builder switch. 5998 5999.. index:: -fuse-ld=name 6000 6001:switch:`-fuse-ld={name}` 6002 Linker to be used. The default is ``bfd`` for :file:`ld.bfd`, 6003 the alternative being ``gold`` for :file:`ld.gold`. The later is 6004 a more recent and faster linker, but only available on GNU/Linux 6005 platforms. 6006 6007.. _Binding_with_gnatbind: 6008 6009Binding with ``gnatbind`` 6010========================= 6011 6012.. index:: ! gnatbind 6013 6014This chapter describes the GNAT binder, ``gnatbind``, which is used 6015to bind compiled GNAT objects. 6016 6017The ``gnatbind`` program performs four separate functions: 6018 6019* Checks that a program is consistent, in accordance with the rules in 6020 Chapter 10 of the Ada Reference Manual. In particular, error 6021 messages are generated if a program uses inconsistent versions of a 6022 given unit. 6023 6024* Checks that an acceptable order of elaboration exists for the program 6025 and issues an error message if it cannot find an order of elaboration 6026 that satisfies the rules in Chapter 10 of the Ada Language Manual. 6027 6028* Generates a main program incorporating the given elaboration order. 6029 This program is a small Ada package (body and spec) that 6030 must be subsequently compiled 6031 using the GNAT compiler. The necessary compilation step is usually 6032 performed automatically by ``gnatlink``. The two most important 6033 functions of this program 6034 are to call the elaboration routines of units in an appropriate order 6035 and to call the main program. 6036 6037* Determines the set of object files required by the given main program. 6038 This information is output in the forms of comments in the generated program, 6039 to be read by the ``gnatlink`` utility used to link the Ada application. 6040 6041.. _Running_gnatbind: 6042 6043Running ``gnatbind`` 6044-------------------- 6045 6046The form of the ``gnatbind`` command is 6047 6048.. code-block:: sh 6049 6050 $ gnatbind [ switches ] mainprog[.ali] [ switches ] 6051 6052 6053where :file:`mainprog.adb` is the Ada file containing the main program 6054unit body. ``gnatbind`` constructs an Ada 6055package in two files whose names are 6056:file:`b~mainprog.ads`, and :file:`b~mainprog.adb`. 6057For example, if given the 6058parameter :file:`hello.ali`, for a main program contained in file 6059:file:`hello.adb`, the binder output files would be :file:`b~hello.ads` 6060and :file:`b~hello.adb`. 6061 6062When doing consistency checking, the binder takes into consideration 6063any source files it can locate. For example, if the binder determines 6064that the given main program requires the package ``Pack``, whose 6065:file:`.ALI` 6066file is :file:`pack.ali` and whose corresponding source spec file is 6067:file:`pack.ads`, it attempts to locate the source file :file:`pack.ads` 6068(using the same search path conventions as previously described for the 6069``gcc`` command). If it can locate this source file, it checks that 6070the time stamps 6071or source checksums of the source and its references to in :file:`ALI` files 6072match. In other words, any :file:`ALI` files that mentions this spec must have 6073resulted from compiling this version of the source file (or in the case 6074where the source checksums match, a version close enough that the 6075difference does not matter). 6076 6077.. index:: Source files, use by binder 6078 6079The effect of this consistency checking, which includes source files, is 6080that the binder ensures that the program is consistent with the latest 6081version of the source files that can be located at bind time. Editing a 6082source file without compiling files that depend on the source file cause 6083error messages to be generated by the binder. 6084 6085For example, suppose you have a main program :file:`hello.adb` and a 6086package ``P``, from file :file:`p.ads` and you perform the following 6087steps: 6088 6089* Enter ``gcc -c hello.adb`` to compile the main program. 6090 6091* Enter ``gcc -c p.ads`` to compile package ``P``. 6092 6093* Edit file :file:`p.ads`. 6094 6095* Enter ``gnatbind hello``. 6096 6097At this point, the file :file:`p.ali` contains an out-of-date time stamp 6098because the file :file:`p.ads` has been edited. The attempt at binding 6099fails, and the binder generates the following error messages: 6100 6101 6102:: 6103 6104 error: "hello.adb" must be recompiled ("p.ads" has been modified) 6105 error: "p.ads" has been modified and must be recompiled 6106 6107 6108Now both files must be recompiled as indicated, and then the bind can 6109succeed, generating a main program. You need not normally be concerned 6110with the contents of this file, but for reference purposes a sample 6111binder output file is given in :ref:`Example_of_Binder_Output_File`. 6112 6113In most normal usage, the default mode of ``gnatbind`` which is to 6114generate the main package in Ada, as described in the previous section. 6115In particular, this means that any Ada programmer can read and understand 6116the generated main program. It can also be debugged just like any other 6117Ada code provided the :switch:`-g` switch is used for 6118``gnatbind`` and ``gnatlink``. 6119 6120.. _Switches_for_gnatbind: 6121 6122Switches for ``gnatbind`` 6123------------------------- 6124 6125The following switches are available with ``gnatbind``; details will 6126be presented in subsequent sections. 6127 6128 6129.. index:: --version (gnatbind) 6130 6131:switch:`--version` 6132 Display Copyright and version, then exit disregarding all other options. 6133 6134 6135.. index:: --help (gnatbind) 6136 6137:switch:`--help` 6138 If :switch:`--version` was not used, display usage, then exit disregarding 6139 all other options. 6140 6141 6142.. index:: -a (gnatbind) 6143 6144:switch:`-a` 6145 Indicates that, if supported by the platform, the adainit procedure should 6146 be treated as an initialisation routine by the linker (a constructor). This 6147 is intended to be used by the Project Manager to automatically initialize 6148 shared Stand-Alone Libraries. 6149 6150 6151.. index:: -aO (gnatbind) 6152 6153:switch:`-aO` 6154 Specify directory to be searched for ALI files. 6155 6156 6157.. index:: -aI (gnatbind) 6158 6159:switch:`-aI` 6160 Specify directory to be searched for source file. 6161 6162 6163.. index:: -A (gnatbind) 6164 6165:switch:`-A[={filename}]` 6166 Output ALI list (to standard output or to the named file). 6167 6168 6169.. index:: -b (gnatbind) 6170 6171:switch:`-b` 6172 Generate brief messages to :file:`stderr` even if verbose mode set. 6173 6174 6175.. index:: -c (gnatbind) 6176 6177:switch:`-c` 6178 Check only, no generation of binder output file. 6179 6180 6181.. index:: -dnn[k|m] (gnatbind) 6182 6183:switch:`-d{nn}[k|m]` 6184 This switch can be used to change the default task stack size value 6185 to a specified size ``nn``, which is expressed in bytes by default, or 6186 in kilobytes when suffixed with ``k`` or in megabytes when suffixed 6187 with ``m``. 6188 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent, 6189 in effect, to completing all task specs with 6190 6191 .. code-block:: ada 6192 6193 pragma Storage_Size (nn); 6194 6195 When they do not already have such a pragma. 6196 6197 6198.. index:: -D (gnatbind) 6199 6200:switch:`-D{nn}[k|m]` 6201 This switch can be used to change the default secondary stack size value 6202 to a specified size ``nn``, which is expressed in bytes by default, or 6203 in kilobytes when suffixed with ``k`` or in megabytes when suffixed 6204 with ``m``. 6205 6206 The secondary stack is used to deal with functions that return a variable 6207 sized result, for example a function returning an unconstrained 6208 String. There are two ways in which this secondary stack is allocated. 6209 6210 For most targets, the secondary stack grows on demand and is allocated 6211 as a chain of blocks in the heap. The -D option is not very 6212 relevant. It only give some control over the size of the allocated 6213 blocks (whose size is the minimum of the default secondary stack size value, 6214 and the actual size needed for the current allocation request). 6215 6216 For certain targets, notably VxWorks 653 and bare board targets, 6217 the secondary stack is allocated by carving off a chunk of the primary task 6218 stack. By default this is a fixed percentage of the primary task stack as 6219 defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per 6220 task using the Secondary_Stack_Size pragma/aspect. The -D option is used to 6221 define the size of the environment task's secondary stack. 6222 6223 6224.. index:: -e (gnatbind) 6225 6226:switch:`-e` 6227 Output complete list of elaboration-order dependencies. 6228 6229 6230.. index:: -Ea (gnatbind) 6231 6232:switch:`-Ea` 6233 Store tracebacks in exception occurrences when the target supports it. 6234 The "a" is for "address"; tracebacks will contain hexadecimal addresses, 6235 unless symbolic tracebacks are enabled. 6236 6237 See also the packages ``GNAT.Traceback`` and 6238 ``GNAT.Traceback.Symbolic`` for more information. 6239 Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer` 6240 ``gcc`` option. 6241 6242 6243.. index:: -Es (gnatbind) 6244 6245:switch:`-Es` 6246 Store tracebacks in exception occurrences when the target supports it. 6247 The "s" is for "symbolic"; symbolic tracebacks are enabled. 6248 6249 6250.. index:: -E (gnatbind) 6251 6252:switch:`-E` 6253 Currently the same as ``-Ea``. 6254 6255 6256.. index:: -f (gnatbind) 6257 6258:switch:`-f{elab-order}` 6259 Force elaboration order. 6260 6261.. index:: -F (gnatbind) 6262 6263:switch:`-F` 6264 Force the checks of elaboration flags. ``gnatbind`` does not normally 6265 generate checks of elaboration flags for the main executable, except when 6266 a Stand-Alone Library is used. However, there are cases when this cannot be 6267 detected by gnatbind. An example is importing an interface of a Stand-Alone 6268 Library through a pragma Import and only specifying through a linker switch 6269 this Stand-Alone Library. This switch is used to guarantee that elaboration 6270 flag checks are generated. 6271 6272 6273.. index:: -h (gnatbind) 6274 6275:switch:`-h` 6276 Output usage (help) information. 6277 6278 6279 .. index:: -H32 (gnatbind) 6280 6281:switch:`-H32` 6282 Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types). 6283 For further details see :ref:`Dynamic_Allocation_Control`. 6284 6285 6286 .. index:: -H64 (gnatbind) 6287 .. index:: __gnat_malloc 6288 6289:switch:`-H64` 6290 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types). 6291 For further details see :ref:`Dynamic_Allocation_Control`. 6292 6293 6294 .. index:: -I (gnatbind) 6295 6296:switch:`-I` 6297 Specify directory to be searched for source and ALI files. 6298 6299 6300 .. index:: -I- (gnatbind) 6301 6302:switch:`-I-` 6303 Do not look for sources in the current directory where ``gnatbind`` was 6304 invoked, and do not look for ALI files in the directory containing the 6305 ALI file named in the ``gnatbind`` command line. 6306 6307 6308 .. index:: -l (gnatbind) 6309 6310:switch:`-l` 6311 Output chosen elaboration order. 6312 6313 6314 .. index:: -L (gnatbind) 6315 6316:switch:`-L{xxx}` 6317 Bind the units for library building. In this case the ``adainit`` and 6318 ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`) 6319 are renamed to :samp:`{xxx}init` and 6320 :samp:`{xxx}final`. 6321 Implies -n. 6322 (:ref:`GNAT_and_Libraries`, for more details.) 6323 6324 6325 .. index:: -M (gnatbind) 6326 6327:switch:`-M{xyz}` 6328 Rename generated main program from main to xyz. This option is 6329 supported on cross environments only. 6330 6331 6332 .. index:: -m (gnatbind) 6333 6334:switch:`-m{n}` 6335 Limit number of detected errors or warnings to ``n``, where ``n`` is 6336 in the range 1..999999. The default value if no switch is 6337 given is 9999. If the number of warnings reaches this limit, then a 6338 message is output and further warnings are suppressed, the bind 6339 continues in this case. If the number of errors reaches this 6340 limit, then a message is output and the bind is abandoned. 6341 A value of zero means that no limit is enforced. The equal 6342 sign is optional. 6343 6344 6345 .. index:: -n (gnatbind) 6346 6347:switch:`-n` 6348 No main program. 6349 6350 6351 .. index:: -nostdinc (gnatbind) 6352 6353:switch:`-nostdinc` 6354 Do not look for sources in the system default directory. 6355 6356 6357 .. index:: -nostdlib (gnatbind) 6358 6359:switch:`-nostdlib` 6360 Do not look for library files in the system default directory. 6361 6362 6363 .. index:: --RTS (gnatbind) 6364 6365:switch:`--RTS={rts-path}` 6366 Specifies the default location of the runtime library. Same meaning as the 6367 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). 6368 6369 .. index:: -o (gnatbind) 6370 6371:switch:`-o {file}` 6372 Name the output file ``file`` (default is :file:`b~`xxx`.adb`). 6373 Note that if this option is used, then linking must be done manually, 6374 gnatlink cannot be used. 6375 6376 6377 .. index:: -O (gnatbind) 6378 6379:switch:`-O[={filename}]` 6380 Output object list (to standard output or to the named file). 6381 6382 6383 .. index:: -p (gnatbind) 6384 6385:switch:`-p` 6386 Pessimistic (worst-case) elaboration order. 6387 6388 6389 .. index:: -P (gnatbind) 6390 6391:switch:`-P` 6392 Generate binder file suitable for CodePeer. 6393 6394 6395 .. index:: -R (gnatbind) 6396 6397:switch:`-R` 6398 Output closure source list, which includes all non-run-time units that are 6399 included in the bind. 6400 6401 6402 .. index:: -Ra (gnatbind) 6403 6404:switch:`-Ra` 6405 Like :switch:`-R` but the list includes run-time units. 6406 6407 6408 .. index:: -s (gnatbind) 6409 6410:switch:`-s` 6411 Require all source files to be present. 6412 6413 6414 .. index:: -S (gnatbind) 6415 6416:switch:`-S{xxx}` 6417 Specifies the value to be used when detecting uninitialized scalar 6418 objects with pragma Initialize_Scalars. 6419 The ``xxx`` string specified with the switch is one of: 6420 6421 * ``in`` for an invalid value. 6422 6423 If zero is invalid for the discrete type in question, 6424 then the scalar value is set to all zero bits. 6425 For signed discrete types, the largest possible negative value of 6426 the underlying scalar is set (i.e. a one bit followed by all zero bits). 6427 For unsigned discrete types, the underlying scalar value is set to all 6428 one bits. For floating-point types, a NaN value is set 6429 (see body of package System.Scalar_Values for exact values). 6430 6431 * ``lo`` for low value. 6432 6433 If zero is invalid for the discrete type in question, 6434 then the scalar value is set to all zero bits. 6435 For signed discrete types, the largest possible negative value of 6436 the underlying scalar is set (i.e. a one bit followed by all zero bits). 6437 For unsigned discrete types, the underlying scalar value is set to all 6438 zero bits. For floating-point, a small value is set 6439 (see body of package System.Scalar_Values for exact values). 6440 6441 * ``hi`` for high value. 6442 6443 If zero is invalid for the discrete type in question, 6444 then the scalar value is set to all one bits. 6445 For signed discrete types, the largest possible positive value of 6446 the underlying scalar is set (i.e. a zero bit followed by all one bits). 6447 For unsigned discrete types, the underlying scalar value is set to all 6448 one bits. For floating-point, a large value is set 6449 (see body of package System.Scalar_Values for exact values). 6450 6451 * ``xx`` for hex value (two hex digits). 6452 6453 The underlying scalar is set to a value consisting of repeated bytes, whose 6454 value corresponds to the given value. For example if ``BF`` is given, 6455 then a 32-bit scalar value will be set to the bit patterm ``16#BFBFBFBF#``. 6456 6457 .. index:: GNAT_INIT_SCALARS 6458 6459 In addition, you can specify :switch:`-Sev` to indicate that the value is 6460 to be set at run time. In this case, the program will look for an environment 6461 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one 6462 of :samp:`in/lo/hi/{xx}` with the same meanings as above. 6463 If no environment variable is found, or if it does not have a valid value, 6464 then the default is ``in`` (invalid values). 6465 6466.. index:: -static (gnatbind) 6467 6468:switch:`-static` 6469 Link against a static GNAT run time. 6470 6471 6472 .. index:: -shared (gnatbind) 6473 6474:switch:`-shared` 6475 Link against a shared GNAT run time when available. 6476 6477 6478 .. index:: -t (gnatbind) 6479 6480:switch:`-t` 6481 Tolerate time stamp and other consistency errors. 6482 6483 6484 .. index:: -T (gnatbind) 6485 6486:switch:`-T{n}` 6487 Set the time slice value to ``n`` milliseconds. If the system supports 6488 the specification of a specific time slice value, then the indicated value 6489 is used. If the system does not support specific time slice values, but 6490 does support some general notion of round-robin scheduling, then any 6491 nonzero value will activate round-robin scheduling. 6492 6493 A value of zero is treated specially. It turns off time 6494 slicing, and in addition, indicates to the tasking run time that the 6495 semantics should match as closely as possible the Annex D 6496 requirements of the Ada RM, and in particular sets the default 6497 scheduling policy to ``FIFO_Within_Priorities``. 6498 6499 6500 .. index:: -u (gnatbind) 6501 6502:switch:`-u{n}` 6503 Enable dynamic stack usage, with ``n`` results stored and displayed 6504 at program termination. A result is generated when a task 6505 terminates. Results that can't be stored are displayed on the fly, at 6506 task termination. This option is currently not supported on Itanium 6507 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.) 6508 6509 6510 .. index:: -v (gnatbind) 6511 6512:switch:`-v` 6513 Verbose mode. Write error messages, header, summary output to 6514 :file:`stdout`. 6515 6516 6517 .. index:: -V (gnatbind) 6518 6519:switch:`-V{key}={value}` 6520 Store the given association of ``key`` to ``value`` in the bind environment. 6521 Values stored this way can be retrieved at run time using 6522 ``GNAT.Bind_Environment``. 6523 6524 6525 .. index:: -w (gnatbind) 6526 6527:switch:`-w{x}` 6528 Warning mode; ``x`` = s/e for suppress/treat as error. 6529 6530 6531 .. index:: -Wx (gnatbind) 6532 6533:switch:`-Wx{e}` 6534 Override default wide character encoding for standard Text_IO files. 6535 6536 6537 .. index:: -x (gnatbind) 6538 6539:switch:`-x` 6540 Exclude source files (check object consistency only). 6541 6542 6543 .. index:: -Xnnn (gnatbind) 6544 6545:switch:`-X{nnn}` 6546 Set default exit status value, normally 0 for POSIX compliance. 6547 6548 6549 .. index:: -y (gnatbind) 6550 6551:switch:`-y` 6552 Enable leap seconds support in ``Ada.Calendar`` and its children. 6553 6554 6555 .. index:: -z (gnatbind) 6556 6557:switch:`-z` 6558 No main subprogram. 6559 6560You may obtain this listing of switches by running ``gnatbind`` with 6561no arguments. 6562 6563 6564.. _Consistency-Checking_Modes: 6565 6566Consistency-Checking Modes 6567^^^^^^^^^^^^^^^^^^^^^^^^^^ 6568 6569As described earlier, by default ``gnatbind`` checks 6570that object files are consistent with one another and are consistent 6571with any source files it can locate. The following switches control binder 6572access to sources. 6573 6574 6575 .. index:: -s (gnatbind) 6576 6577:switch:`-s` 6578 Require source files to be present. In this mode, the binder must be 6579 able to locate all source files that are referenced, in order to check 6580 their consistency. In normal mode, if a source file cannot be located it 6581 is simply ignored. If you specify this switch, a missing source 6582 file is an error. 6583 6584 6585 .. index:: -Wx (gnatbind) 6586 6587:switch:`-Wx{e}` 6588 Override default wide character encoding for standard Text_IO files. 6589 Normally the default wide character encoding method used for standard 6590 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for 6591 the main source input (see description of switch 6592 :switch:`-gnatWx` for the compiler). The 6593 use of this switch for the binder (which has the same set of 6594 possible arguments) overrides this default as specified. 6595 6596 6597 .. index:: -x (gnatbind) 6598 6599:switch:`-x` 6600 Exclude source files. In this mode, the binder only checks that ALI 6601 files are consistent with one another. Source files are not accessed. 6602 The binder runs faster in this mode, and there is still a guarantee that 6603 the resulting program is self-consistent. 6604 If a source file has been edited since it was last compiled, and you 6605 specify this switch, the binder will not detect that the object 6606 file is out of date with respect to the source file. Note that this is the 6607 mode that is automatically used by ``gnatmake`` because in this 6608 case the checking against sources has already been performed by 6609 ``gnatmake`` in the course of compilation (i.e., before binding). 6610 6611 6612.. _Binder_Error_Message_Control: 6613 6614Binder Error Message Control 6615^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6616 6617The following switches provide control over the generation of error 6618messages from the binder: 6619 6620 6621 6622 .. index:: -v (gnatbind) 6623 6624:switch:`-v` 6625 Verbose mode. In the normal mode, brief error messages are generated to 6626 :file:`stderr`. If this switch is present, a header is written 6627 to :file:`stdout` and any error messages are directed to :file:`stdout`. 6628 All that is written to :file:`stderr` is a brief summary message. 6629 6630 6631 .. index:: -b (gnatbind) 6632 6633:switch:`-b` 6634 Generate brief error messages to :file:`stderr` even if verbose mode is 6635 specified. This is relevant only when used with the 6636 :switch:`-v` switch. 6637 6638 6639 .. index:: -m (gnatbind) 6640 6641:switch:`-m{n}` 6642 Limits the number of error messages to ``n``, a decimal integer in the 6643 range 1-999. The binder terminates immediately if this limit is reached. 6644 6645 6646 .. index:: -M (gnatbind) 6647 6648:switch:`-M{xxx}` 6649 Renames the generated main program from ``main`` to ``xxx``. 6650 This is useful in the case of some cross-building environments, where 6651 the actual main program is separate from the one generated 6652 by ``gnatbind``. 6653 6654 6655 .. index:: -ws (gnatbind) 6656 .. index:: Warnings 6657 6658:switch:`-ws` 6659 Suppress all warning messages. 6660 6661 6662 .. index:: -we (gnatbind) 6663 6664:switch:`-we` 6665 Treat any warning messages as fatal errors. 6666 6667 6668 .. index:: -t (gnatbind) 6669 .. index:: Time stamp checks, in binder 6670 .. index:: Binder consistency checks 6671 .. index:: Consistency checks, in binder 6672 6673:switch:`-t` 6674 The binder performs a number of consistency checks including: 6675 6676 6677 * Check that time stamps of a given source unit are consistent 6678 6679 * Check that checksums of a given source unit are consistent 6680 6681 * Check that consistent versions of ``GNAT`` were used for compilation 6682 6683 * Check consistency of configuration pragmas as required 6684 6685 Normally failure of such checks, in accordance with the consistency 6686 requirements of the Ada Reference Manual, causes error messages to be 6687 generated which abort the binder and prevent the output of a binder 6688 file and subsequent link to obtain an executable. 6689 6690 The :switch:`-t` switch converts these error messages 6691 into warnings, so that 6692 binding and linking can continue to completion even in the presence of such 6693 errors. The result may be a failed link (due to missing symbols), or a 6694 non-functional executable which has undefined semantics. 6695 6696 .. note:: 6697 6698 This means that :switch:`-t` should be used only in unusual situations, 6699 with extreme care. 6700 6701.. _Elaboration_Control: 6702 6703Elaboration Control 6704^^^^^^^^^^^^^^^^^^^ 6705 6706The following switches provide additional control over the elaboration 6707order. For full details see :ref:`Elaboration_Order_Handling_in_GNAT`. 6708 6709 6710.. index:: -f (gnatbind) 6711 6712:switch:`-f{elab-order}` 6713 Force elaboration order. 6714 6715 ``elab-order`` should be the name of a "forced elaboration order file", that 6716 is, a text file containing library item names, one per line. A name of the 6717 form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A 6718 name of the form "some.unit%b" or "some.unit (body)" denotes the body of 6719 Some.Unit. Each pair of lines is taken to mean that there is an elaboration 6720 dependence of the second line on the first. For example, if the file 6721 contains: 6722 6723 .. code-block:: ada 6724 6725 this (spec) 6726 this (body) 6727 that (spec) 6728 that (body) 6729 6730 then the spec of This will be elaborated before the body of This, and the 6731 body of This will be elaborated before the spec of That, and the spec of That 6732 will be elaborated before the body of That. The first and last of these three 6733 dependences are already required by Ada rules, so this file is really just 6734 forcing the body of This to be elaborated before the spec of That. 6735 6736 The given order must be consistent with Ada rules, or else ``gnatbind`` will 6737 give elaboration cycle errors. For example, if you say x (body) should be 6738 elaborated before x (spec), there will be a cycle, because Ada rules require 6739 x (spec) to be elaborated before x (body); you can't have the spec and body 6740 both elaborated before each other. 6741 6742 If you later add "with That;" to the body of This, there will be a cycle, in 6743 which case you should erase either "this (body)" or "that (spec)" from the 6744 above forced elaboration order file. 6745 6746 Blank lines and Ada-style comments are ignored. Unit names that do not exist 6747 in the program are ignored. Units in the GNAT predefined library are also 6748 ignored. 6749 6750 6751 .. index:: -p (gnatbind) 6752 6753:switch:`-p` 6754 Normally the binder attempts to choose an elaboration order that is 6755 likely to minimize the likelihood of an elaboration order error resulting 6756 in raising a ``Program_Error`` exception. This switch reverses the 6757 action of the binder, and requests that it deliberately choose an order 6758 that is likely to maximize the likelihood of an elaboration error. 6759 This is useful in ensuring portability and avoiding dependence on 6760 accidental fortuitous elaboration ordering. 6761 6762 Normally it only makes sense to use the :switch:`-p` 6763 switch if dynamic 6764 elaboration checking is used (:switch:`-gnatE` switch used for compilation). 6765 This is because in the default static elaboration mode, all necessary 6766 ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted. 6767 These implicit pragmas are still respected by the binder in 6768 :switch:`-p` mode, so a 6769 safe elaboration order is assured. 6770 6771 Note that :switch:`-p` is not intended for 6772 production use; it is more for debugging/experimental use. 6773 6774.. _Output_Control: 6775 6776Output Control 6777^^^^^^^^^^^^^^ 6778 6779The following switches allow additional control over the output 6780generated by the binder. 6781 6782 6783 .. index:: -c (gnatbind) 6784 6785:switch:`-c` 6786 Check only. Do not generate the binder output file. In this mode the 6787 binder performs all error checks but does not generate an output file. 6788 6789 6790 .. index:: -e (gnatbind) 6791 6792:switch:`-e` 6793 Output complete list of elaboration-order dependencies, showing the 6794 reason for each dependency. This output can be rather extensive but may 6795 be useful in diagnosing problems with elaboration order. The output is 6796 written to :file:`stdout`. 6797 6798 6799 .. index:: -h (gnatbind) 6800 6801:switch:`-h` 6802 Output usage information. The output is written to :file:`stdout`. 6803 6804 6805 .. index:: -K (gnatbind) 6806 6807:switch:`-K` 6808 Output linker options to :file:`stdout`. Includes library search paths, 6809 contents of pragmas Ident and Linker_Options, and libraries added 6810 by ``gnatbind``. 6811 6812 6813 .. index:: -l (gnatbind) 6814 6815:switch:`-l` 6816 Output chosen elaboration order. The output is written to :file:`stdout`. 6817 6818 6819 .. index:: -O (gnatbind) 6820 6821:switch:`-O` 6822 Output full names of all the object files that must be linked to provide 6823 the Ada component of the program. The output is written to :file:`stdout`. 6824 This list includes the files explicitly supplied and referenced by the user 6825 as well as implicitly referenced run-time unit files. The latter are 6826 omitted if the corresponding units reside in shared libraries. The 6827 directory names for the run-time units depend on the system configuration. 6828 6829 6830 .. index:: -o (gnatbind) 6831 6832:switch:`-o {file}` 6833 Set name of output file to ``file`` instead of the normal 6834 :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada 6835 binder generated body filename. 6836 Note that if this option is used, then linking must be done manually. 6837 It is not possible to use gnatlink in this case, since it cannot locate 6838 the binder file. 6839 6840 6841 .. index:: -r (gnatbind) 6842 6843:switch:`-r` 6844 Generate list of ``pragma Restrictions`` that could be applied to 6845 the current unit. This is useful for code audit purposes, and also may 6846 be used to improve code generation in some cases. 6847 6848 6849.. _Dynamic_Allocation_Control: 6850 6851Dynamic Allocation Control 6852^^^^^^^^^^^^^^^^^^^^^^^^^^ 6853 6854The heap control switches -- :switch:`-H32` and :switch:`-H64` -- 6855determine whether dynamic allocation uses 32-bit or 64-bit memory. 6856They only affect compiler-generated allocations via ``__gnat_malloc``; 6857explicit calls to ``malloc`` and related functions from the C 6858run-time library are unaffected. 6859 6860:switch:`-H32` 6861 Allocate memory on 32-bit heap 6862 6863 6864:switch:`-H64` 6865 Allocate memory on 64-bit heap. This is the default 6866 unless explicitly overridden by a ``'Size`` clause on the access type. 6867 6868These switches are only effective on VMS platforms. 6869 6870 6871.. _Binding_with_Non-Ada_Main_Programs: 6872 6873Binding with Non-Ada Main Programs 6874^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6875 6876The description so far has assumed that the main 6877program is in Ada, and that the task of the binder is to generate a 6878corresponding function ``main`` that invokes this Ada main 6879program. GNAT also supports the building of executable programs where 6880the main program is not in Ada, but some of the called routines are 6881written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`). 6882The following switch is used in this situation: 6883 6884 6885 .. index:: -n (gnatbind) 6886 6887:switch:`-n` 6888 No main program. The main program is not in Ada. 6889 6890In this case, most of the functions of the binder are still required, 6891but instead of generating a main program, the binder generates a file 6892containing the following callable routines: 6893 6894 .. index:: adainit 6895 6896 ``adainit`` 6897 You must call this routine to initialize the Ada part of the program by 6898 calling the necessary elaboration routines. A call to ``adainit`` is 6899 required before the first call to an Ada subprogram. 6900 6901 Note that it is assumed that the basic execution environment must be setup 6902 to be appropriate for Ada execution at the point where the first Ada 6903 subprogram is called. In particular, if the Ada code will do any 6904 floating-point operations, then the FPU must be setup in an appropriate 6905 manner. For the case of the x86, for example, full precision mode is 6906 required. The procedure GNAT.Float_Control.Reset may be used to ensure 6907 that the FPU is in the right state. 6908 6909 .. index:: adafinal 6910 6911 ``adafinal`` 6912 You must call this routine to perform any library-level finalization 6913 required by the Ada subprograms. A call to ``adafinal`` is required 6914 after the last call to an Ada subprogram, and before the program 6915 terminates. 6916 6917.. index:: -n (gnatbind) 6918.. index:: Binder, multiple input files 6919 6920If the :switch:`-n` switch 6921is given, more than one ALI file may appear on 6922the command line for ``gnatbind``. The normal ``closure`` 6923calculation is performed for each of the specified units. Calculating 6924the closure means finding out the set of units involved by tracing 6925|with| references. The reason it is necessary to be able to 6926specify more than one ALI file is that a given program may invoke two or 6927more quite separate groups of Ada units. 6928 6929The binder takes the name of its output file from the last specified ALI 6930file, unless overridden by the use of the :switch:`-o file`. 6931 6932.. index:: -o (gnatbind) 6933 6934The output is an Ada unit in source form that can be compiled with GNAT. 6935This compilation occurs automatically as part of the ``gnatlink`` 6936processing. 6937 6938Currently the GNAT run time requires a FPU using 80 bits mode 6939precision. Under targets where this is not the default it is required to 6940call GNAT.Float_Control.Reset before using floating point numbers (this 6941include float computation, float input and output) in the Ada code. A 6942side effect is that this could be the wrong mode for the foreign code 6943where floating point computation could be broken after this call. 6944 6945 6946.. _Binding_Programs_with_No_Main_Subprogram: 6947 6948Binding Programs with No Main Subprogram 6949^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6950 6951It is possible to have an Ada program which does not have a main 6952subprogram. This program will call the elaboration routines of all the 6953packages, then the finalization routines. 6954 6955The following switch is used to bind programs organized in this manner: 6956 6957 .. index:: -z (gnatbind) 6958 6959:switch:`-z` 6960 Normally the binder checks that the unit name given on the command line 6961 corresponds to a suitable main subprogram. When this switch is used, 6962 a list of ALI files can be given, and the execution of the program 6963 consists of elaboration of these units in an appropriate order. Note 6964 that the default wide character encoding method for standard Text_IO 6965 files is always set to Brackets if this switch is set (you can use 6966 the binder switch 6967 :switch:`-Wx` to override this default). 6968 6969 6970.. _Command-Line_Access: 6971 6972Command-Line Access 6973------------------- 6974 6975The package ``Ada.Command_Line`` provides access to the command-line 6976arguments and program name. In order for this interface to operate 6977correctly, the two variables 6978 6979.. code-block:: c 6980 6981 int gnat_argc; 6982 char **gnat_argv; 6983 6984.. index:: gnat_argv 6985.. index:: gnat_argc 6986 6987are declared in one of the GNAT library routines. These variables must 6988be set from the actual ``argc`` and ``argv`` values passed to the 6989main program. With no *n* present, ``gnatbind`` 6990generates the C main program to automatically set these variables. 6991If the *n* switch is used, there is no automatic way to 6992set these variables. If they are not set, the procedures in 6993``Ada.Command_Line`` will not be available, and any attempt to use 6994them will raise ``Constraint_Error``. If command line access is 6995required, your main program must set ``gnat_argc`` and 6996``gnat_argv`` from the ``argc`` and ``argv`` values passed to 6997it. 6998 6999 7000.. _Search_Paths_for_gnatbind: 7001 7002Search Paths for ``gnatbind`` 7003----------------------------- 7004 7005The binder takes the name of an ALI file as its argument and needs to 7006locate source files as well as other ALI files to verify object consistency. 7007 7008For source files, it follows exactly the same search rules as ``gcc`` 7009(see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the 7010directories searched are: 7011 7012* The directory containing the ALI file named in the command line, unless 7013 the switch :switch:`-I-` is specified. 7014 7015* All directories specified by :switch:`-I` 7016 switches on the ``gnatbind`` 7017 command line, in the order given. 7018 7019 .. index:: ADA_PRJ_OBJECTS_FILE 7020 7021* Each of the directories listed in the text file whose name is given 7022 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable. 7023 7024 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat 7025 driver when project files are used. It should not normally be set 7026 by other means. 7027 7028 .. index:: ADA_OBJECTS_PATH 7029 7030* Each of the directories listed in the value of the 7031 :envvar:`ADA_OBJECTS_PATH` environment variable. 7032 Construct this value 7033 exactly as the :envvar:`PATH` environment variable: a list of directory 7034 names separated by colons (semicolons when working with the NT version 7035 of GNAT). 7036 7037* The content of the :file:`ada_object_path` file which is part of the GNAT 7038 installation tree and is used to store standard libraries such as the 7039 GNAT Run Time Library (RTL) unless the switch :switch:`-nostdlib` is 7040 specified. See :ref:`Installing_a_library` 7041 7042.. index:: -I (gnatbind) 7043.. index:: -aI (gnatbind) 7044.. index:: -aO (gnatbind) 7045 7046In the binder the switch :switch:`-I` 7047is used to specify both source and 7048library file paths. Use :switch:`-aI` 7049instead if you want to specify 7050source paths only, and :switch:`-aO` 7051if you want to specify library paths 7052only. This means that for the binder 7053:switch:`-I{dir}` is equivalent to 7054:switch:`-aI{dir}` 7055:switch:`-aO`{dir}`. 7056The binder generates the bind file (a C language source file) in the 7057current working directory. 7058 7059.. index:: Ada 7060.. index:: System 7061.. index:: Interfaces 7062.. index:: GNAT 7063 7064The packages ``Ada``, ``System``, and ``Interfaces`` and their 7065children make up the GNAT Run-Time Library, together with the package 7066GNAT and its children, which contain a set of useful additional 7067library functions provided by GNAT. The sources for these units are 7068needed by the compiler and are kept together in one directory. The ALI 7069files and object files generated by compiling the RTL are needed by the 7070binder and the linker and are kept together in one directory, typically 7071different from the directory containing the sources. In a normal 7072installation, you need not specify these directory names when compiling 7073or binding. Either the environment variables or the built-in defaults 7074cause these files to be found. 7075 7076Besides simplifying access to the RTL, a major use of search paths is 7077in compiling sources from multiple directories. This can make 7078development environments much more flexible. 7079 7080 7081.. _Examples_of_gnatbind_Usage: 7082 7083Examples of ``gnatbind`` Usage 7084------------------------------ 7085 7086Here are some examples of ``gnatbind`` invovations: 7087 7088 :: 7089 7090 gnatbind hello 7091 7092 The main program ``Hello`` (source program in :file:`hello.adb`) is 7093 bound using the standard switch settings. The generated main program is 7094 :file:`b~hello.adb`. This is the normal, default use of the binder. 7095 7096 :: 7097 7098 gnatbind hello -o mainprog.adb 7099 7100 The main program ``Hello`` (source program in :file:`hello.adb`) is 7101 bound using the standard switch settings. The generated main program is 7102 :file:`mainprog.adb` with the associated spec in 7103 :file:`mainprog.ads`. Note that you must specify the body here not the 7104 spec. Note that if this option is used, then linking must be done manually, 7105 since gnatlink will not be able to find the generated file. 7106 7107 7108.. _Linking_with_gnatlink: 7109 7110Linking with ``gnatlink`` 7111========================= 7112 7113.. index:: ! gnatlink 7114 7115This chapter discusses ``gnatlink``, a tool that links 7116an Ada program and builds an executable file. This utility 7117invokes the system linker (via the ``gcc`` command) 7118with a correct list of object files and library references. 7119``gnatlink`` automatically determines the list of files and 7120references for the Ada part of a program. It uses the binder file 7121generated by the ``gnatbind`` to determine this list. 7122 7123.. _Running_gnatlink: 7124 7125Running ``gnatlink`` 7126-------------------- 7127 7128The form of the ``gnatlink`` command is 7129 7130 7131.. code-block:: sh 7132 7133 $ gnatlink [ switches ] mainprog [.ali] 7134 [ non-Ada objects ] [ linker options ] 7135 7136 7137 7138The arguments of ``gnatlink`` (switches, main ``ALI`` file, 7139non-Ada objects 7140or linker options) may be in any order, provided that no non-Ada object may 7141be mistaken for a main :file:`ALI` file. 7142Any file name :file:`F` without the :file:`.ali` 7143extension will be taken as the main :file:`ALI` file if a file exists 7144whose name is the concatenation of :file:`F` and :file:`.ali`. 7145 7146:file:`mainprog.ali` references the ALI file of the main program. 7147The :file:`.ali` extension of this file can be omitted. From this 7148reference, ``gnatlink`` locates the corresponding binder file 7149:file:`b~mainprog.adb` and, using the information in this file along 7150with the list of non-Ada objects and linker options, constructs a 7151linker command file to create the executable. 7152 7153The arguments other than the ``gnatlink`` switches and the main 7154:file:`ALI` file are passed to the linker uninterpreted. 7155They typically include the names of 7156object files for units written in other languages than Ada and any library 7157references required to resolve references in any of these foreign language 7158units, or in ``Import`` pragmas in any Ada units. 7159 7160``linker options`` is an optional list of linker specific 7161switches. 7162The default linker called by gnatlink is ``gcc`` which in 7163turn calls the appropriate system linker. 7164 7165One useful option for the linker is :switch:`-s`: it reduces the size of the 7166executable by removing all symbol table and relocation information from the 7167executable. 7168 7169Standard options for the linker such as :switch:`-lmy_lib` or 7170:switch:`-Ldir` can be added as is. 7171For options that are not recognized by 7172``gcc`` as linker options, use the ``gcc`` switches 7173:switch:`-Xlinker` or :switch:`-Wl,`. 7174 7175Refer to the GCC documentation for 7176details. 7177 7178Here is an example showing how to generate a linker map: 7179 7180.. code-block:: sh 7181 7182 $ gnatlink my_prog -Wl,-Map,MAPFILE 7183 7184 7185Using ``linker options`` it is possible to set the program stack and 7186heap size. 7187See :ref:`Setting_Stack_Size_from_gnatlink` and 7188:ref:`Setting_Heap_Size_from_gnatlink`. 7189 7190``gnatlink`` determines the list of objects required by the Ada 7191program and prepends them to the list of objects passed to the linker. 7192``gnatlink`` also gathers any arguments set by the use of 7193``pragma Linker_Options`` and adds them to the list of arguments 7194presented to the linker. 7195 7196 7197.. _Switches_for_gnatlink: 7198 7199Switches for ``gnatlink`` 7200------------------------- 7201 7202The following switches are available with the ``gnatlink`` utility: 7203 7204.. index:: --version (gnatlink) 7205 7206:switch:`--version` 7207 Display Copyright and version, then exit disregarding all other options. 7208 7209 7210.. index:: --help (gnatlink) 7211 7212:switch:`--help` 7213 If :switch:`--version` was not used, display usage, then exit disregarding 7214 all other options. 7215 7216 7217.. index:: Command line length 7218.. index:: -f (gnatlink) 7219 7220:switch:`-f` 7221 On some targets, the command line length is limited, and ``gnatlink`` 7222 will generate a separate file for the linker if the list of object files 7223 is too long. 7224 The :switch:`-f` switch forces this file 7225 to be generated even if 7226 the limit is not exceeded. This is useful in some cases to deal with 7227 special situations where the command line length is exceeded. 7228 7229 7230.. index:: Debugging information, including 7231.. index:: -g (gnatlink) 7232 7233:switch:`-g` 7234 The option to include debugging information causes the Ada bind file (in 7235 other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`. 7236 In addition, the binder does not delete the :file:`b~mainprog.adb`, 7237 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files. 7238 Without :switch:`-g`, the binder removes these files by default. 7239 7240.. index:: -n (gnatlink) 7241 7242:switch:`-n` 7243 Do not compile the file generated by the binder. This may be used when 7244 a link is rerun with different options, but there is no need to recompile 7245 the binder file. 7246 7247 7248.. index:: -v (gnatlink) 7249 7250:switch:`-v` 7251 Verbose mode. Causes additional information to be output, including a full 7252 list of the included object files. 7253 This switch option is most useful when you want 7254 to see what set of object files are being used in the link step. 7255 7256 7257.. index:: -v -v (gnatlink) 7258 7259:switch:`-v -v` 7260 Very verbose mode. Requests that the compiler operate in verbose mode when 7261 it compiles the binder file, and that the system linker run in verbose mode. 7262 7263 7264.. index:: -o (gnatlink) 7265 7266:switch:`-o {exec-name}` 7267 ``exec-name`` specifies an alternate name for the generated 7268 executable program. If this switch is omitted, the executable has the same 7269 name as the main unit. For example, ``gnatlink try.ali`` creates 7270 an executable called :file:`try`. 7271 7272 7273.. index:: -B (gnatlink) 7274 7275:switch:`-B{dir}` 7276 Load compiler executables (for example, ``gnat1``, the Ada compiler) 7277 from ``dir`` instead of the default location. Only use this switch 7278 when multiple versions of the GNAT compiler are available. 7279 See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection` 7280 for further details. You would normally use the :switch:`-b` or 7281 :switch:`-V` switch instead. 7282 7283 7284.. index:: -M (gnatlink) 7285 7286:switch:`-M` 7287 When linking an executable, create a map file. The name of the map file 7288 has the same name as the executable with extension ".map". 7289 7290 7291.. index:: -M= (gnatlink) 7292 7293:switch:`-M={mapfile}` 7294 When linking an executable, create a map file. The name of the map file is 7295 ``mapfile``. 7296 7297 7298.. index:: --GCC=compiler_name (gnatlink) 7299 7300:switch:`--GCC={compiler_name}` 7301 Program used for compiling the binder file. The default is 7302 ``gcc``. You need to use quotes around ``compiler_name`` if 7303 ``compiler_name`` contains spaces or other separator characters. 7304 As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to 7305 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always 7306 inserted after your command name. Thus in the above example the compiler 7307 command that will be used by ``gnatlink`` will be ``foo -c -x -y``. 7308 A limitation of this syntax is that the name and path name of the executable 7309 itself must not include any embedded spaces. If the compiler executable is 7310 different from the default one (gcc or <prefix>-gcc), then the back-end 7311 switches in the ALI file are not used to compile the binder generated source. 7312 For example, this is the case with ``--GCC="foo -x -y"``. But the back end 7313 switches will be used for ``--GCC="gcc -gnatv"``. If several 7314 ``--GCC=compiler_name`` are used, only the last ``compiler_name`` 7315 is taken into account. However, all the additional switches are also taken 7316 into account. Thus, 7317 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to 7318 ``--GCC="bar -x -y -z -t"``. 7319 7320 7321.. index:: --LINK= (gnatlink) 7322 7323:switch:`--LINK={name}` 7324 ``name`` is the name of the linker to be invoked. This is especially 7325 useful in mixed language programs since languages such as C++ require 7326 their own linker to be used. When this switch is omitted, the default 7327 name for the linker is ``gcc``. When this switch is used, the 7328 specified linker is called instead of ``gcc`` with exactly the same 7329 parameters that would have been passed to ``gcc`` so if the desired 7330 linker requires different parameters it is necessary to use a wrapper 7331 script that massages the parameters before invoking the real linker. It 7332 may be useful to control the exact invocation by using the verbose 7333 switch. 7334 7335 7336.. _Using_the_GNU_make_Utility: 7337 7338Using the GNU ``make`` Utility 7339============================== 7340 7341.. index:: make (GNU), GNU make 7342 7343This chapter offers some examples of makefiles that solve specific 7344problems. It does not explain how to write a makefile, nor does it try to replace the 7345``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`). 7346 7347All the examples in this section are specific to the GNU version of 7348make. Although ``make`` is a standard utility, and the basic language 7349is the same, these examples use some advanced features found only in 7350``GNU make``. 7351 7352.. _Using_gnatmake_in_a_Makefile: 7353 7354Using gnatmake in a Makefile 7355---------------------------- 7356 7357.. index makefile (GNU make) 7358 7359Complex project organizations can be handled in a very powerful way by 7360using GNU make combined with gnatmake. For instance, here is a Makefile 7361which allows you to build each subsystem of a big project into a separate 7362shared library. Such a makefile allows you to significantly reduce the link 7363time of very big applications while maintaining full coherence at 7364each step of the build process. 7365 7366The list of dependencies are handled automatically by 7367``gnatmake``. The Makefile is simply used to call gnatmake in each of 7368the appropriate directories. 7369 7370Note that you should also read the example on how to automatically 7371create the list of directories 7372(:ref:`Automatically_Creating_a_List_of_Directories`) 7373which might help you in case your project has a lot of subdirectories. 7374 7375 7376.. code-block:: makefile 7377 7378 ## This Makefile is intended to be used with the following directory 7379 ## configuration: 7380 ## - The sources are split into a series of csc (computer software components) 7381 ## Each of these csc is put in its own directory. 7382 ## Their name are referenced by the directory names. 7383 ## They will be compiled into shared library (although this would also work 7384 ## with static libraries 7385 ## - The main program (and possibly other packages that do not belong to any 7386 ## csc is put in the top level directory (where the Makefile is). 7387 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) 7388 ## \\_ second_csc (sources) __ lib (will contain the library) 7389 ## \\_ ... 7390 ## Although this Makefile is build for shared library, it is easy to modify 7391 ## to build partial link objects instead (modify the lines with -shared and 7392 ## gnatlink below) 7393 ## 7394 ## With this makefile, you can change any file in the system or add any new 7395 ## file, and everything will be recompiled correctly (only the relevant shared 7396 ## objects will be recompiled, and the main program will be re-linked). 7397 7398 # The list of computer software component for your project. This might be 7399 # generated automatically. 7400 CSC_LIST=aa bb cc 7401 7402 # Name of the main program (no extension) 7403 MAIN=main 7404 7405 # If we need to build objects with -fPIC, uncomment the following line 7406 #NEED_FPIC=-fPIC 7407 7408 # The following variable should give the directory containing libgnat.so 7409 # You can get this directory through 'gnatls -v'. This is usually the last 7410 # directory in the Object_Path. 7411 GLIB=... 7412 7413 # The directories for the libraries 7414 # (This macro expands the list of CSC to the list of shared libraries, you 7415 # could simply use the expanded form: 7416 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so 7417 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so} 7418 7419 ${MAIN}: objects ${LIB_DIR} 7420 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared 7421 gnatlink ${MAIN} ${CSC_LIST:%=-l%} 7422 7423 objects:: 7424 # recompile the sources 7425 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%} 7426 7427 # Note: In a future version of GNAT, the following commands will be simplified 7428 # by a new tool, gnatmlib 7429 ${LIB_DIR}: 7430 mkdir -p ${dir $@ } 7431 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat 7432 cd ${dir $@ } && cp -f ../*.ali . 7433 7434 # The dependencies for the modules 7435 # Note that we have to force the expansion of *.o, since in some cases 7436 # make won't be able to do it itself. 7437 aa/lib/libaa.so: ${wildcard aa/*.o} 7438 bb/lib/libbb.so: ${wildcard bb/*.o} 7439 cc/lib/libcc.so: ${wildcard cc/*.o} 7440 7441 # Make sure all of the shared libraries are in the path before starting the 7442 # program 7443 run:: 7444 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN} 7445 7446 clean:: 7447 ${RM} -rf ${CSC_LIST:%=%/lib} 7448 ${RM} ${CSC_LIST:%=%/*.ali} 7449 ${RM} ${CSC_LIST:%=%/*.o} 7450 ${RM} *.o *.ali ${MAIN} 7451 7452 7453.. _Automatically_Creating_a_List_of_Directories: 7454 7455Automatically Creating a List of Directories 7456-------------------------------------------- 7457 7458In most makefiles, you will have to specify a list of directories, and 7459store it in a variable. For small projects, it is often easier to 7460specify each of them by hand, since you then have full control over what 7461is the proper order for these directories, which ones should be 7462included. 7463 7464However, in larger projects, which might involve hundreds of 7465subdirectories, it might be more convenient to generate this list 7466automatically. 7467 7468The example below presents two methods. The first one, although less 7469general, gives you more control over the list. It involves wildcard 7470characters, that are automatically expanded by ``make``. Its 7471shortcoming is that you need to explicitly specify some of the 7472organization of your project, such as for instance the directory tree 7473depth, whether some directories are found in a separate tree, etc. 7474 7475The second method is the most general one. It requires an external 7476program, called ``find``, which is standard on all Unix systems. All 7477the directories found under a given root directory will be added to the 7478list. 7479 7480.. code-block:: makefile 7481 7482 # The examples below are based on the following directory hierarchy: 7483 # All the directories can contain any number of files 7484 # ROOT_DIRECTORY -> a -> aa -> aaa 7485 # -> ab 7486 # -> ac 7487 # -> b -> ba -> baa 7488 # -> bb 7489 # -> bc 7490 # This Makefile creates a variable called DIRS, that can be reused any time 7491 # you need this list (see the other examples in this section) 7492 7493 # The root of your project's directory hierarchy 7494 ROOT_DIRECTORY=. 7495 7496 #### 7497 # First method: specify explicitly the list of directories 7498 # This allows you to specify any subset of all the directories you need. 7499 #### 7500 7501 DIRS := a/aa/ a/ab/ b/ba/ 7502 7503 #### 7504 # Second method: use wildcards 7505 # Note that the argument(s) to wildcard below should end with a '/'. 7506 # Since wildcards also return file names, we have to filter them out 7507 # to avoid duplicate directory names. 7508 # We thus use make's ``dir`` and ``sort`` functions. 7509 # It sets DIRs to the following value (note that the directories aaa and baa 7510 # are not given, unless you change the arguments to wildcard). 7511 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ 7512 #### 7513 7514 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/ 7515 ${ROOT_DIRECTORY}/*/*/}}} 7516 7517 #### 7518 # Third method: use an external program 7519 # This command is much faster if run on local disks, avoiding NFS slowdowns. 7520 # This is the most complete command: it sets DIRs to the following value: 7521 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc 7522 #### 7523 7524 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print} 7525 7526 7527 7528.. _Generating_the_Command_Line_Switches: 7529 7530Generating the Command Line Switches 7531------------------------------------ 7532 7533Once you have created the list of directories as explained in the 7534previous section (:ref:`Automatically_Creating_a_List_of_Directories`), 7535you can easily generate the command line arguments to pass to gnatmake. 7536 7537For the sake of completeness, this example assumes that the source path 7538is not the same as the object path, and that you have two separate lists 7539of directories. 7540 7541.. code-block:: makefile 7542 7543 # see "Automatically creating a list of directories" to create 7544 # these variables 7545 SOURCE_DIRS= 7546 OBJECT_DIRS= 7547 7548 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}} 7549 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}} 7550 7551 all: 7552 gnatmake ${GNATMAKE_SWITCHES} main_unit 7553 7554 7555.. _Overcoming_Command_Line_Length_Limits: 7556 7557Overcoming Command Line Length Limits 7558------------------------------------- 7559 7560One problem that might be encountered on big projects is that many 7561operating systems limit the length of the command line. It is thus hard to give 7562gnatmake the list of source and object directories. 7563 7564This example shows how you can set up environment variables, which will 7565make ``gnatmake`` behave exactly as if the directories had been 7566specified on the command line, but have a much higher length limit (or 7567even none on most systems). 7568 7569It assumes that you have created a list of directories in your Makefile, 7570using one of the methods presented in 7571:ref:`Automatically_Creating_a_List_of_Directories`. 7572For the sake of completeness, we assume that the object 7573path (where the ALI files are found) is different from the sources patch. 7574 7575Note a small trick in the Makefile below: for efficiency reasons, we 7576create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are 7577expanded immediately by ``make``. This way we overcome the standard 7578make behavior which is to expand the variables only when they are 7579actually used. 7580 7581On Windows, if you are using the standard Windows command shell, you must 7582replace colons with semicolons in the assignments to these variables. 7583 7584.. code-block:: makefile 7585 7586 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH. 7587 # This is the same thing as putting the -I arguments on the command line. 7588 # (the equivalent of using -aI on the command line would be to define 7589 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH). 7590 # You can of course have different values for these variables. 7591 # 7592 # Note also that we need to keep the previous values of these variables, since 7593 # they might have been set before running 'make' to specify where the GNAT 7594 # library is installed. 7595 7596 # see "Automatically creating a list of directories" to create these 7597 # variables 7598 SOURCE_DIRS= 7599 OBJECT_DIRS= 7600 7601 empty:= 7602 space:=${empty} ${empty} 7603 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}} 7604 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}} 7605 ADA_INCLUDE_PATH += ${SOURCE_LIST} 7606 ADA_OBJECTS_PATH += ${OBJECT_LIST} 7607 export ADA_INCLUDE_PATH 7608 export ADA_OBJECTS_PATH 7609 7610 all: 7611 gnatmake main_unit 7612