1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gnat_ugn.info 4@documentencoding UTF-8 5@ifinfo 6@*Generated by Sphinx 1.4.6.@* 7@end ifinfo 8@settitle GNAT User's Guide for Native Platforms 9@defindex ge 10@paragraphindent 0 11@exampleindent 4 12@finalout 13@dircategory GNU Ada Tools 14@direntry 15* gnat_ugn: (gnat_ugn.info). gnat_ugn 16@end direntry 17 18@definfoenclose strong,`,' 19@definfoenclose emph,`,' 20@c %**end of header 21 22@copying 23@quotation 24GNAT User's Guide for Native Platforms , Dec 11, 2020 25 26AdaCore 27 28Copyright @copyright{} 2008-2021, Free Software Foundation 29@end quotation 30 31@end copying 32 33@titlepage 34@title GNAT User's Guide for Native Platforms 35@insertcopying 36@end titlepage 37@contents 38 39@c %** start of user preamble 40 41@c %** end of user preamble 42 43@ifnottex 44@node Top, About This Guide 45@top GNAT User's Guide for Native Platforms 46@insertcopying 47@end ifnottex 48 49@c %**start of body 50@anchor{gnat_ugn doc}@anchor{0} 51@emph{GNAT, The GNU Ada Development Environment} 52 53 54@include gcc-common.texi 55GCC version @value{version-GCC}@* 56AdaCore 57 58Permission is granted to copy, distribute and/or modify this document 59under the terms of the GNU Free Documentation License, Version 1.3 or 60any later version published by the Free Software Foundation; with no 61Invariant Sections, with the Front-Cover Texts being 62"GNAT User's Guide for Native Platforms", 63and with no Back-Cover Texts. A copy of the license is 64included in the section entitled @ref{1,,GNU Free Documentation License}. 65 66@menu 67* About This Guide:: 68* Getting Started with GNAT:: 69* The GNAT Compilation Model:: 70* Building Executable Programs with GNAT:: 71* GNAT Utility Programs:: 72* GNAT and Program Execution:: 73* Platform-Specific Information:: 74* Example of Binder Output File:: 75* Elaboration Order Handling in GNAT:: 76* Inline Assembler:: 77* GNU Free Documentation License:: 78* Index:: 79 80@detailmenu 81 --- The Detailed Node Listing --- 82 83About This Guide 84 85* What This Guide Contains:: 86* What You Should Know before Reading This Guide:: 87* Related Information:: 88* Conventions:: 89 90Getting Started with GNAT 91 92* System Requirements:: 93* Running GNAT:: 94* Running a Simple Ada Program:: 95* Running a Program with Multiple Units:: 96 97The GNAT Compilation Model 98 99* Source Representation:: 100* Foreign Language Representation:: 101* File Naming Topics and Utilities:: 102* Configuration Pragmas:: 103* Generating Object Files:: 104* Source Dependencies:: 105* The Ada Library Information Files:: 106* Binding an Ada Program:: 107* GNAT and Libraries:: 108* Conditional Compilation:: 109* Mixed Language Programming:: 110* GNAT and Other Compilation Models:: 111* Using GNAT Files with External Tools:: 112 113Foreign Language Representation 114 115* Latin-1:: 116* Other 8-Bit Codes:: 117* Wide_Character Encodings:: 118* Wide_Wide_Character Encodings:: 119 120File Naming Topics and Utilities 121 122* File Naming Rules:: 123* Using Other File Names:: 124* Alternative File Naming Schemes:: 125* Handling Arbitrary File Naming Conventions with gnatname:: 126* File Name Krunching with gnatkr:: 127* Renaming Files with gnatchop:: 128 129Handling Arbitrary File Naming Conventions with gnatname 130 131* Arbitrary File Naming Conventions:: 132* Running gnatname:: 133* Switches for gnatname:: 134* Examples of gnatname Usage:: 135 136File Name Krunching with gnatkr 137 138* About gnatkr:: 139* Using gnatkr:: 140* Krunching Method:: 141* Examples of gnatkr Usage:: 142 143Renaming Files with gnatchop 144 145* Handling Files with Multiple Units:: 146* Operating gnatchop in Compilation Mode:: 147* Command Line for gnatchop:: 148* Switches for gnatchop:: 149* Examples of gnatchop Usage:: 150 151Configuration Pragmas 152 153* Handling of Configuration Pragmas:: 154* The Configuration Pragmas Files:: 155 156GNAT and Libraries 157 158* Introduction to Libraries in GNAT:: 159* General Ada Libraries:: 160* Stand-alone Ada Libraries:: 161* Rebuilding the GNAT Run-Time Library:: 162 163General Ada Libraries 164 165* Building a library:: 166* Installing a library:: 167* Using a library:: 168 169Stand-alone Ada Libraries 170 171* Introduction to Stand-alone Libraries:: 172* Building a Stand-alone Library:: 173* Creating a Stand-alone Library to be used in a non-Ada context:: 174* Restrictions in Stand-alone Libraries:: 175 176Conditional Compilation 177 178* Modeling Conditional Compilation in Ada:: 179* Preprocessing with gnatprep:: 180* Integrated Preprocessing:: 181 182Modeling Conditional Compilation in Ada 183 184* Use of Boolean Constants:: 185* Debugging - A Special Case:: 186* Conditionalizing Declarations:: 187* Use of Alternative Implementations:: 188* Preprocessing:: 189 190Preprocessing with gnatprep 191 192* Preprocessing Symbols:: 193* Using gnatprep:: 194* Switches for gnatprep:: 195* Form of Definitions File:: 196* Form of Input Text for gnatprep:: 197 198Mixed Language Programming 199 200* Interfacing to C:: 201* Calling Conventions:: 202* Building Mixed Ada and C++ Programs:: 203* Generating Ada Bindings for C and C++ headers:: 204* Generating C Headers for Ada Specifications:: 205 206Building Mixed Ada and C++ Programs 207 208* Interfacing to C++:: 209* Linking a Mixed C++ & Ada Program:: 210* A Simple Example:: 211* Interfacing with C++ constructors:: 212* Interfacing with C++ at the Class Level:: 213 214Generating Ada Bindings for C and C++ headers 215 216* Running the Binding Generator:: 217* Generating Bindings for C++ Headers:: 218* Switches:: 219 220Generating C Headers for Ada Specifications 221 222* Running the C Header Generator:: 223 224GNAT and Other Compilation Models 225 226* Comparison between GNAT and C/C++ Compilation Models:: 227* Comparison between GNAT and Conventional Ada Library Models:: 228 229Using GNAT Files with External Tools 230 231* Using Other Utility Programs with GNAT:: 232* The External Symbol Naming Scheme of GNAT:: 233 234Building Executable Programs with GNAT 235 236* Building with gnatmake:: 237* Compiling with gcc:: 238* Compiler Switches:: 239* Linker Switches:: 240* Binding with gnatbind:: 241* Linking with gnatlink:: 242* Using the GNU make Utility:: 243 244Building with gnatmake 245 246* Running gnatmake:: 247* Switches for gnatmake:: 248* Mode Switches for gnatmake:: 249* Notes on the Command Line:: 250* How gnatmake Works:: 251* Examples of gnatmake Usage:: 252 253Compiling with gcc 254 255* Compiling Programs:: 256* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. 257* Order of Compilation Issues:: 258* Examples:: 259 260Compiler Switches 261 262* Alphabetical List of All Switches:: 263* Output and Error Message Control:: 264* Warning Message Control:: 265* Debugging and Assertion Control:: 266* Validity Checking:: 267* Style Checking:: 268* Run-Time Checks:: 269* Using gcc for Syntax Checking:: 270* Using gcc for Semantic Checking:: 271* Compiling Different Versions of Ada:: 272* Character Set Control:: 273* File Naming Control:: 274* Subprogram Inlining Control:: 275* Auxiliary Output Control:: 276* Debugging Control:: 277* Exception Handling Control:: 278* Units to Sources Mapping Files:: 279* Code Generation Control:: 280 281Binding with gnatbind 282 283* Running gnatbind:: 284* Switches for gnatbind:: 285* Command-Line Access:: 286* Search Paths for gnatbind:: 287* Examples of gnatbind Usage:: 288 289Switches for gnatbind 290 291* Consistency-Checking Modes:: 292* Binder Error Message Control:: 293* Elaboration Control:: 294* Output Control:: 295* Dynamic Allocation Control:: 296* Binding with Non-Ada Main Programs:: 297* Binding Programs with No Main Subprogram:: 298 299Linking with gnatlink 300 301* Running gnatlink:: 302* Switches for gnatlink:: 303 304Using the GNU make Utility 305 306* Using gnatmake in a Makefile:: 307* Automatically Creating a List of Directories:: 308* Generating the Command Line Switches:: 309* Overcoming Command Line Length Limits:: 310 311GNAT Utility Programs 312 313* The File Cleanup Utility gnatclean:: 314* The GNAT Library Browser gnatls:: 315 316The File Cleanup Utility gnatclean 317 318* Running gnatclean:: 319* Switches for gnatclean:: 320 321The GNAT Library Browser gnatls 322 323* Running gnatls:: 324* Switches for gnatls:: 325* Example of gnatls Usage:: 326 327GNAT and Program Execution 328 329* Running and Debugging Ada Programs:: 330* Profiling:: 331* Improving Performance:: 332* Overflow Check Handling in GNAT:: 333* Performing Dimensionality Analysis in GNAT:: 334* Stack Related Facilities:: 335* Memory Management Issues:: 336 337Running and Debugging Ada Programs 338 339* The GNAT Debugger GDB:: 340* Running GDB:: 341* Introduction to GDB Commands:: 342* Using Ada Expressions:: 343* Calling User-Defined Subprograms:: 344* Using the next Command in a Function:: 345* Stopping When Ada Exceptions Are Raised:: 346* Ada Tasks:: 347* Debugging Generic Units:: 348* Remote Debugging with gdbserver:: 349* GNAT Abnormal Termination or Failure to Terminate:: 350* Naming Conventions for GNAT Source Files:: 351* Getting Internal Debugging Information:: 352* Stack Traceback:: 353* Pretty-Printers for the GNAT runtime:: 354 355Stack Traceback 356 357* Non-Symbolic Traceback:: 358* Symbolic Traceback:: 359 360Profiling 361 362* Profiling an Ada Program with gprof:: 363 364Profiling an Ada Program with gprof 365 366* Compilation for profiling:: 367* Program execution:: 368* Running gprof:: 369* Interpretation of profiling results:: 370 371Improving Performance 372 373* Performance Considerations:: 374* Text_IO Suggestions:: 375* Reducing Size of Executables with Unused Subprogram/Data Elimination:: 376 377Performance Considerations 378 379* Controlling Run-Time Checks:: 380* Use of Restrictions:: 381* Optimization Levels:: 382* Debugging Optimized Code:: 383* Inlining of Subprograms:: 384* Floating Point Operations:: 385* Vectorization of loops:: 386* Other Optimization Switches:: 387* Optimization and Strict Aliasing:: 388* Aliased Variables and Optimization:: 389* Atomic Variables and Optimization:: 390* Passive Task Optimization:: 391 392Reducing Size of Executables with Unused Subprogram/Data Elimination 393 394* About unused subprogram/data elimination:: 395* Compilation options:: 396* Example of unused subprogram/data elimination:: 397 398Overflow Check Handling in GNAT 399 400* Background:: 401* Management of Overflows in GNAT:: 402* Specifying the Desired Mode:: 403* Default Settings:: 404* Implementation Notes:: 405 406Stack Related Facilities 407 408* Stack Overflow Checking:: 409* Static Stack Usage Analysis:: 410* Dynamic Stack Usage Analysis:: 411 412Memory Management Issues 413 414* Some Useful Memory Pools:: 415* The GNAT Debug Pool Facility:: 416 417Platform-Specific Information 418 419* Run-Time Libraries:: 420* Specifying a Run-Time Library:: 421* GNU/Linux Topics:: 422* Microsoft Windows Topics:: 423* Mac OS Topics:: 424 425Run-Time Libraries 426 427* Summary of Run-Time Configurations:: 428 429Specifying a Run-Time Library 430 431* Choosing the Scheduling Policy:: 432 433GNU/Linux Topics 434 435* Required Packages on GNU/Linux:: 436 437Microsoft Windows Topics 438 439* Using GNAT on Windows:: 440* Using a network installation of GNAT:: 441* CONSOLE and WINDOWS subsystems:: 442* Temporary Files:: 443* Disabling Command Line Argument Expansion:: 444* Windows Socket Timeouts:: 445* Mixed-Language Programming on Windows:: 446* Windows Specific Add-Ons:: 447 448Mixed-Language Programming on Windows 449 450* Windows Calling Conventions:: 451* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. 452* Using DLLs with GNAT:: 453* Building DLLs with GNAT Project files:: 454* Building DLLs with GNAT:: 455* Building DLLs with gnatdll:: 456* Ada DLLs and Finalization:: 457* Creating a Spec for Ada DLLs:: 458* GNAT and Windows Resources:: 459* Using GNAT DLLs from Microsoft Visual Studio Applications:: 460* Debugging a DLL:: 461* Setting Stack Size from gnatlink:: 462* Setting Heap Size from gnatlink:: 463 464Windows Calling Conventions 465 466* C Calling Convention:: 467* Stdcall Calling Convention:: 468* Win32 Calling Convention:: 469* DLL Calling Convention:: 470 471Using DLLs with GNAT 472 473* Creating an Ada Spec for the DLL Services:: 474* Creating an Import Library:: 475 476Building DLLs with gnatdll 477 478* Limitations When Using Ada DLLs from Ada:: 479* Exporting Ada Entities:: 480* Ada DLLs and Elaboration:: 481 482Creating a Spec for Ada DLLs 483 484* Creating the Definition File:: 485* Using gnatdll:: 486 487GNAT and Windows Resources 488 489* Building Resources:: 490* Compiling Resources:: 491* Using Resources:: 492 493Debugging a DLL 494 495* Program and DLL Both Built with GCC/GNAT:: 496* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: 497 498Windows Specific Add-Ons 499 500* Win32Ada:: 501* wPOSIX:: 502 503Mac OS Topics 504 505* Codesigning the Debugger:: 506 507Elaboration Order Handling in GNAT 508 509* Elaboration Code:: 510* Elaboration Order:: 511* Checking the Elaboration Order:: 512* Controlling the Elaboration Order in Ada:: 513* Controlling the Elaboration Order in GNAT:: 514* Mixing Elaboration Models:: 515* ABE Diagnostics:: 516* SPARK Diagnostics:: 517* Elaboration Circularities:: 518* Resolving Elaboration Circularities:: 519* Elaboration-related Compiler Switches:: 520* Summary of Procedures for Elaboration Control:: 521* Inspecting the Chosen Elaboration Order:: 522 523Inline Assembler 524 525* Basic Assembler Syntax:: 526* A Simple Example of Inline Assembler:: 527* Output Variables in Inline Assembler:: 528* Input Variables in Inline Assembler:: 529* Inlining Inline Assembler Code:: 530* Other Asm Functionality:: 531 532Other Asm Functionality 533 534* The Clobber Parameter:: 535* The Volatile Parameter:: 536 537@end detailmenu 538@end menu 539 540@node About This Guide,Getting Started with GNAT,Top,Top 541@anchor{gnat_ugn/about_this_guide about-this-guide}@anchor{2}@anchor{gnat_ugn/about_this_guide doc}@anchor{3}@anchor{gnat_ugn/about_this_guide gnat-user-s-guide-for-native-platforms}@anchor{4}@anchor{gnat_ugn/about_this_guide id1}@anchor{5} 542@chapter About This Guide 543 544 545 546This guide describes the use of GNAT, 547a compiler and software development 548toolset for the full Ada programming language. 549It documents the features of the compiler and tools, and explains 550how to use them to build Ada applications. 551 552GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, and it may also be 553invoked in Ada 83 compatibility mode. 554By default, GNAT assumes Ada 2012, but you can override with a 555compiler switch (@ref{6,,Compiling Different Versions of Ada}) 556to explicitly specify the language version. 557Throughout this manual, references to 'Ada' without a year suffix 558apply to all Ada versions of the language, starting with Ada 95. 559 560@menu 561* What This Guide Contains:: 562* What You Should Know before Reading This Guide:: 563* Related Information:: 564* Conventions:: 565 566@end menu 567 568@node What This Guide Contains,What You Should Know before Reading This Guide,,About This Guide 569@anchor{gnat_ugn/about_this_guide what-this-guide-contains}@anchor{7} 570@section What This Guide Contains 571 572 573This guide contains the following chapters: 574 575 576@itemize * 577 578@item 579@ref{8,,Getting Started with GNAT} describes how to get started compiling 580and running Ada programs with the GNAT Ada programming environment. 581 582@item 583@ref{9,,The GNAT Compilation Model} describes the compilation model used 584by GNAT. 585 586@item 587@ref{a,,Building Executable Programs with GNAT} describes how to use the 588main GNAT tools to build executable programs, and it also gives examples of 589using the GNU make utility with GNAT. 590 591@item 592@ref{b,,GNAT Utility Programs} explains the various utility programs that 593are included in the GNAT environment 594 595@item 596@ref{c,,GNAT and Program Execution} covers a number of topics related to 597running, debugging, and tuning the performace of programs developed 598with GNAT 599@end itemize 600 601Appendices cover several additional topics: 602 603 604@itemize * 605 606@item 607@ref{d,,Platform-Specific Information} describes the different run-time 608library implementations and also presents information on how to use 609GNAT on several specific platforms 610 611@item 612@ref{e,,Example of Binder Output File} shows the source code for the binder 613output file for a sample program. 614 615@item 616@ref{f,,Elaboration Order Handling in GNAT} describes how GNAT helps 617you deal with elaboration order issues. 618 619@item 620@ref{10,,Inline Assembler} shows how to use the inline assembly facility 621in an Ada program. 622@end itemize 623 624@node What You Should Know before Reading This Guide,Related Information,What This Guide Contains,About This Guide 625@anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{11} 626@section What You Should Know before Reading This Guide 627 628 629@geindex Ada 95 Language Reference Manual 630 631@geindex Ada 2005 Language Reference Manual 632 633This guide assumes a basic familiarity with the Ada 95 language, as 634described in the International Standard ANSI/ISO/IEC-8652:1995, January 6351995. 636Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in 637the GNAT documentation package. 638 639@node Related Information,Conventions,What You Should Know before Reading This Guide,About This Guide 640@anchor{gnat_ugn/about_this_guide related-information}@anchor{12} 641@section Related Information 642 643 644For further information about Ada and related tools, please refer to the 645following documents: 646 647 648@itemize * 649 650@item 651@cite{Ada 95 Reference Manual}, @cite{Ada 2005 Reference Manual}, and 652@cite{Ada 2012 Reference Manual}, which contain reference 653material for the several revisions of the Ada language standard. 654 655@item 656@cite{GNAT Reference_Manual}, which contains all reference material for the GNAT 657implementation of Ada. 658 659@item 660@cite{Using GNAT Studio}, which describes the GNAT Studio 661Integrated Development Environment. 662 663@item 664@cite{GNAT Studio Tutorial}, which introduces the 665main GNAT Studio features through examples. 666 667@item 668@cite{Debugging with GDB}, 669for all details on the use of the GNU source-level debugger. 670 671@item 672@cite{GNU Emacs Manual}, 673for full information on the extensible editor and programming 674environment Emacs. 675@end itemize 676 677@node Conventions,,Related Information,About This Guide 678@anchor{gnat_ugn/about_this_guide conventions}@anchor{13} 679@section Conventions 680 681 682@geindex Conventions 683@geindex typographical 684 685@geindex Typographical conventions 686 687Following are examples of the typographical and graphic conventions used 688in this guide: 689 690 691@itemize * 692 693@item 694@code{Functions}, @code{utility program names}, @code{standard names}, 695and @code{classes}. 696 697@item 698@code{Option flags} 699 700@item 701@code{File names} 702 703@item 704@code{Variables} 705 706@item 707@emph{Emphasis} 708 709@item 710[optional information or parameters] 711 712@item 713Examples are described by text 714 715@example 716and then shown this way. 717@end example 718 719@item 720Commands that are entered by the user are shown as preceded by a prompt string 721comprising the @code{$} character followed by a space. 722 723@item 724Full file names are shown with the '/' character 725as the directory separator; e.g., @code{parent-dir/subdir/myfile.adb}. 726If you are using GNAT on a Windows platform, please note that 727the '\' character should be used instead. 728@end itemize 729 730@node Getting Started with GNAT,The GNAT Compilation Model,About This Guide,Top 731@anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{14}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{15} 732@chapter Getting Started with GNAT 733 734 735This chapter describes how to use GNAT's command line interface to build 736executable Ada programs. 737On most platforms a visually oriented Integrated Development Environment 738is also available: GNAT Studio. 739GNAT Studio offers a graphical "look and feel", support for development in 740other programming languages, comprehensive browsing features, and 741many other capabilities. 742For information on GNAT Studio please refer to the 743@cite{GNAT Studio documentation}. 744 745@menu 746* System Requirements:: 747* Running GNAT:: 748* Running a Simple Ada Program:: 749* Running a Program with Multiple Units:: 750 751@end menu 752 753@node System Requirements,Running GNAT,,Getting Started with GNAT 754@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{16}@anchor{gnat_ugn/getting_started_with_gnat system-requirements}@anchor{17} 755@section System Requirements 756 757 758Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order 759to get the best experience, we recommend using a machine with as many cores 760as possible since all individual compilations can run in parallel. 761A comfortable setup for a compiler server is a machine with 24 physical cores 762or more, with at least 48 GB of memory (2 GB per core). 763 764For a desktop machine, a minimum of 4 cores is recommended (8 preferred), 765with at least 2GB per core (so 8 to 16GB). 766 767In addition, for running and navigating sources in GNAT Studio smoothly, we 768recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code. 769In other words, we recommend at least 3 GB for for 500K lines of code and 7707.5 GB for 2 million lines of code. 771 772Note that using local and fast drives will also make a difference in terms of 773build and link time. Network drives such as NFS, SMB, or worse, configuration 774management filesystems (such as ClearCase dynamic views) should be avoided as 775much as possible and will produce very degraded performance (typically 2 to 3 776times slower than on local fast drives). If such slow drives cannot be avoided 777for accessing the source code, then you should at least configure your project 778file so that the result of the compilation is stored on a drive local to the 779machine performing the run. This can be achieved by setting the @code{Object_Dir} 780project file attribute. 781 782@node Running GNAT,Running a Simple Ada Program,System Requirements,Getting Started with GNAT 783@anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{18}@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{19} 784@section Running GNAT 785 786 787Three steps are needed to create an executable file from an Ada source 788file: 789 790 791@itemize * 792 793@item 794The source file(s) must be compiled. 795 796@item 797The file(s) must be bound using the GNAT binder. 798 799@item 800All appropriate object files must be linked to produce an executable. 801@end itemize 802 803All three steps are most commonly handled by using the @code{gnatmake} 804utility program that, given the name of the main program, automatically 805performs the necessary compilation, binding and linking steps. 806 807@node Running a Simple Ada Program,Running a Program with Multiple Units,Running GNAT,Getting Started with GNAT 808@anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{1a}@anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{1b} 809@section Running a Simple Ada Program 810 811 812Any text editor may be used to prepare an Ada program. 813(If Emacs is used, the optional Ada mode may be helpful in laying out the 814program.) 815The program text is a normal text file. We will assume in our initial 816example that you have used your editor to prepare the following 817standard format text file: 818 819@example 820with Ada.Text_IO; use Ada.Text_IO; 821procedure Hello is 822begin 823 Put_Line ("Hello WORLD!"); 824end Hello; 825@end example 826 827This file should be named @code{hello.adb}. 828With the normal default file naming conventions, GNAT requires 829that each file 830contain a single compilation unit whose file name is the 831unit name, 832with periods replaced by hyphens; the 833extension is @code{ads} for a 834spec and @code{adb} for a body. 835You can override this default file naming convention by use of the 836special pragma @code{Source_File_Name} (for further information please 837see @ref{1c,,Using Other File Names}). 838Alternatively, if you want to rename your files according to this default 839convention, which is probably more convenient if you will be using GNAT 840for all your compilations, then the @code{gnatchop} utility 841can be used to generate correctly-named source files 842(see @ref{1d,,Renaming Files with gnatchop}). 843 844You can compile the program using the following command (@code{$} is used 845as the command prompt in the examples in this document): 846 847@example 848$ gcc -c hello.adb 849@end example 850 851@code{gcc} is the command used to run the compiler. This compiler is 852capable of compiling programs in several languages, including Ada and 853C. It assumes that you have given it an Ada program if the file extension is 854either @code{.ads} or @code{.adb}, and it will then call 855the GNAT compiler to compile the specified file. 856 857The @code{-c} switch is required. It tells @code{gcc} to only do a 858compilation. (For C programs, @code{gcc} can also do linking, but this 859capability is not used directly for Ada programs, so the @code{-c} 860switch must always be present.) 861 862This compile command generates a file 863@code{hello.o}, which is the object 864file corresponding to your Ada program. It also generates 865an 'Ada Library Information' file @code{hello.ali}, 866which contains additional information used to check 867that an Ada program is consistent. 868 869To build an executable file, use either @code{gnatmake} or gprbuild with 870the name of the main file: these tools are builders that will take care of 871all the necessary build steps in the correct order. 872In particular, these builders automatically recompile any sources that have 873been modified since they were last compiled, or sources that depend 874on such modified sources, so that 'version skew' is avoided. 875 876@geindex Version skew (avoided by `@w{`}gnatmake`@w{`}) 877 878@example 879$ gnatmake hello.adb 880@end example 881 882The result is an executable program called @code{hello}, which can be 883run by entering: 884 885@example 886$ hello 887@end example 888 889assuming that the current directory is on the search path 890for executable programs. 891 892and, if all has gone well, you will see: 893 894@example 895Hello WORLD! 896@end example 897 898appear in response to this command. 899 900@node Running a Program with Multiple Units,,Running a Simple Ada Program,Getting Started with GNAT 901@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{1e}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{1f} 902@section Running a Program with Multiple Units 903 904 905Consider a slightly more complicated example that has three files: a 906main program, and the spec and body of a package: 907 908@example 909package Greetings is 910 procedure Hello; 911 procedure Goodbye; 912end Greetings; 913 914with Ada.Text_IO; use Ada.Text_IO; 915package body Greetings is 916 procedure Hello is 917 begin 918 Put_Line ("Hello WORLD!"); 919 end Hello; 920 921 procedure Goodbye is 922 begin 923 Put_Line ("Goodbye WORLD!"); 924 end Goodbye; 925end Greetings; 926 927with Greetings; 928procedure Gmain is 929begin 930 Greetings.Hello; 931 Greetings.Goodbye; 932end Gmain; 933@end example 934 935Following the one-unit-per-file rule, place this program in the 936following three separate files: 937 938 939@table @asis 940 941@item @emph{greetings.ads} 942 943spec of package @code{Greetings} 944 945@item @emph{greetings.adb} 946 947body of package @code{Greetings} 948 949@item @emph{gmain.adb} 950 951body of main program 952@end table 953 954Note that there is no required order of compilation when using GNAT. 955In particular it is perfectly fine to compile the main program first. 956Also, it is not necessary to compile package specs in the case where 957there is an accompanying body; you only need to compile the body. If you want 958to submit these files to the compiler for semantic checking and not code 959generation, then use the @code{-gnatc} switch: 960 961@example 962$ gcc -c greetings.ads -gnatc 963@end example 964 965Although the compilation can be done in separate steps, in practice it is 966almost always more convenient to use the @code{gnatmake} or @code{gprbuild} tools: 967 968@example 969$ gnatmake gmain.adb 970@end example 971 972@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit 973 974@node The GNAT Compilation Model,Building Executable Programs with GNAT,Getting Started with GNAT,Top 975@anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{20}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{21} 976@chapter The GNAT Compilation Model 977 978 979@geindex GNAT compilation model 980 981@geindex Compilation model 982 983This chapter describes the compilation model used by GNAT. Although 984similar to that used by other languages such as C and C++, this model 985is substantially different from the traditional Ada compilation models, 986which are based on a centralized program library. The chapter covers 987the following material: 988 989 990@itemize * 991 992@item 993Topics related to source file makeup and naming 994 995 996@itemize * 997 998@item 999@ref{22,,Source Representation} 1000 1001@item 1002@ref{23,,Foreign Language Representation} 1003 1004@item 1005@ref{24,,File Naming Topics and Utilities} 1006@end itemize 1007 1008@item 1009@ref{25,,Configuration Pragmas} 1010 1011@item 1012@ref{26,,Generating Object Files} 1013 1014@item 1015@ref{27,,Source Dependencies} 1016 1017@item 1018@ref{28,,The Ada Library Information Files} 1019 1020@item 1021@ref{29,,Binding an Ada Program} 1022 1023@item 1024@ref{2a,,GNAT and Libraries} 1025 1026@item 1027@ref{2b,,Conditional Compilation} 1028 1029@item 1030@ref{2c,,Mixed Language Programming} 1031 1032@item 1033@ref{2d,,GNAT and Other Compilation Models} 1034 1035@item 1036@ref{2e,,Using GNAT Files with External Tools} 1037@end itemize 1038 1039@menu 1040* Source Representation:: 1041* Foreign Language Representation:: 1042* File Naming Topics and Utilities:: 1043* Configuration Pragmas:: 1044* Generating Object Files:: 1045* Source Dependencies:: 1046* The Ada Library Information Files:: 1047* Binding an Ada Program:: 1048* GNAT and Libraries:: 1049* Conditional Compilation:: 1050* Mixed Language Programming:: 1051* GNAT and Other Compilation Models:: 1052* Using GNAT Files with External Tools:: 1053 1054@end menu 1055 1056@node Source Representation,Foreign Language Representation,,The GNAT Compilation Model 1057@anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{22}@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{2f} 1058@section Source Representation 1059 1060 1061@geindex Latin-1 1062 1063@geindex VT 1064@geindex HT 1065@geindex CR 1066@geindex LF 1067@geindex FF 1068 1069Ada source programs are represented in standard text files, using 1070Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar 10717-bit ASCII set, plus additional characters used for 1072representing foreign languages (see @ref{23,,Foreign Language Representation} 1073for support of non-USA character sets). The format effector characters 1074are represented using their standard ASCII encodings, as follows: 1075 1076@quotation 1077 1078 1079@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 1080@item 1081 1082Character 1083 1084@tab 1085 1086Effect 1087 1088@tab 1089 1090Code 1091 1092@item 1093 1094@code{VT} 1095 1096@tab 1097 1098Vertical tab 1099 1100@tab 1101 1102@code{16#0B#} 1103 1104@item 1105 1106@code{HT} 1107 1108@tab 1109 1110Horizontal tab 1111 1112@tab 1113 1114@code{16#09#} 1115 1116@item 1117 1118@code{CR} 1119 1120@tab 1121 1122Carriage return 1123 1124@tab 1125 1126@code{16#0D#} 1127 1128@item 1129 1130@code{LF} 1131 1132@tab 1133 1134Line feed 1135 1136@tab 1137 1138@code{16#0A#} 1139 1140@item 1141 1142@code{FF} 1143 1144@tab 1145 1146Form feed 1147 1148@tab 1149 1150@code{16#0C#} 1151 1152@end multitable 1153 1154@end quotation 1155 1156Source files are in standard text file format. In addition, GNAT will 1157recognize a wide variety of stream formats, in which the end of 1158physical lines is marked by any of the following sequences: 1159@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful 1160in accommodating files that are imported from other operating systems. 1161 1162@geindex End of source file; Source file@comma{} end 1163 1164@geindex SUB (control character) 1165 1166The end of a source file is normally represented by the physical end of 1167file. However, the control character @code{16#1A#} (@code{SUB}) is also 1168recognized as signalling the end of the source file. Again, this is 1169provided for compatibility with other operating systems where this 1170code is used to represent the end of file. 1171 1172@geindex spec (definition) 1173@geindex compilation (definition) 1174 1175Each file contains a single Ada compilation unit, including any pragmas 1176associated with the unit. For example, this means you must place a 1177package declaration (a package @emph{spec}) and the corresponding body in 1178separate files. An Ada @emph{compilation} (which is a sequence of 1179compilation units) is represented using a sequence of files. Similarly, 1180you will place each subunit or child unit in a separate file. 1181 1182@node Foreign Language Representation,File Naming Topics and Utilities,Source Representation,The GNAT Compilation Model 1183@anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{23}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{30} 1184@section Foreign Language Representation 1185 1186 1187GNAT supports the standard character sets defined in Ada as well as 1188several other non-standard character sets for use in localized versions 1189of the compiler (@ref{31,,Character Set Control}). 1190 1191@menu 1192* Latin-1:: 1193* Other 8-Bit Codes:: 1194* Wide_Character Encodings:: 1195* Wide_Wide_Character Encodings:: 1196 1197@end menu 1198 1199@node Latin-1,Other 8-Bit Codes,,Foreign Language Representation 1200@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{32}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{33} 1201@subsection Latin-1 1202 1203 1204@geindex Latin-1 1205 1206The basic character set is Latin-1. This character set is defined by ISO 1207standard 8859, part 1. The lower half (character codes @code{16#00#} 1208... @code{16#7F#)} is identical to standard ASCII coding, but the upper 1209half is used to represent additional characters. These include extended letters 1210used by European languages, such as French accents, the vowels with umlauts 1211used in German, and the extra letter A-ring used in Swedish. 1212 1213@geindex Ada.Characters.Latin_1 1214 1215For a complete list of Latin-1 codes and their encodings, see the source 1216file of library unit @code{Ada.Characters.Latin_1} in file 1217@code{a-chlat1.ads}. 1218You may use any of these extended characters freely in character or 1219string literals. In addition, the extended characters that represent 1220letters can be used in identifiers. 1221 1222@node Other 8-Bit Codes,Wide_Character Encodings,Latin-1,Foreign Language Representation 1223@anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{34}@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{35} 1224@subsection Other 8-Bit Codes 1225 1226 1227GNAT also supports several other 8-bit coding schemes: 1228 1229@geindex Latin-2 1230 1231@geindex ISO 8859-2 1232 1233 1234@table @asis 1235 1236@item @emph{ISO 8859-2 (Latin-2)} 1237 1238Latin-2 letters allowed in identifiers, with uppercase and lowercase 1239equivalence. 1240@end table 1241 1242@geindex Latin-3 1243 1244@geindex ISO 8859-3 1245 1246 1247@table @asis 1248 1249@item @emph{ISO 8859-3 (Latin-3)} 1250 1251Latin-3 letters allowed in identifiers, with uppercase and lowercase 1252equivalence. 1253@end table 1254 1255@geindex Latin-4 1256 1257@geindex ISO 8859-4 1258 1259 1260@table @asis 1261 1262@item @emph{ISO 8859-4 (Latin-4)} 1263 1264Latin-4 letters allowed in identifiers, with uppercase and lowercase 1265equivalence. 1266@end table 1267 1268@geindex ISO 8859-5 1269 1270@geindex Cyrillic 1271 1272 1273@table @asis 1274 1275@item @emph{ISO 8859-5 (Cyrillic)} 1276 1277ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and 1278lowercase equivalence. 1279@end table 1280 1281@geindex ISO 8859-15 1282 1283@geindex Latin-9 1284 1285 1286@table @asis 1287 1288@item @emph{ISO 8859-15 (Latin-9)} 1289 1290ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and 1291lowercase equivalence 1292@end table 1293 1294@geindex code page 437 (IBM PC) 1295 1296 1297@table @asis 1298 1299@item @emph{IBM PC (code page 437)} 1300 1301This code page is the normal default for PCs in the U.S. It corresponds 1302to the original IBM PC character set. This set has some, but not all, of 1303the extended Latin-1 letters, but these letters do not have the same 1304encoding as Latin-1. In this mode, these letters are allowed in 1305identifiers with uppercase and lowercase equivalence. 1306@end table 1307 1308@geindex code page 850 (IBM PC) 1309 1310 1311@table @asis 1312 1313@item @emph{IBM PC (code page 850)} 1314 1315This code page is a modification of 437 extended to include all the 1316Latin-1 letters, but still not with the usual Latin-1 encoding. In this 1317mode, all these letters are allowed in identifiers with uppercase and 1318lowercase equivalence. 1319 1320@item @emph{Full Upper 8-bit} 1321 1322Any character in the range 80-FF allowed in identifiers, and all are 1323considered distinct. In other words, there are no uppercase and lowercase 1324equivalences in this range. This is useful in conjunction with 1325certain encoding schemes used for some foreign character sets (e.g., 1326the typical method of representing Chinese characters on the PC). 1327 1328@item @emph{No Upper-Half} 1329 1330No upper-half characters in the range 80-FF are allowed in identifiers. 1331This gives Ada 83 compatibility for identifier names. 1332@end table 1333 1334For precise data on the encodings permitted, and the uppercase and lowercase 1335equivalences that are recognized, see the file @code{csets.adb} in 1336the GNAT compiler sources. You will need to obtain a full source release 1337of GNAT to obtain this file. 1338 1339@node Wide_Character Encodings,Wide_Wide_Character Encodings,Other 8-Bit Codes,Foreign Language Representation 1340@anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{36}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{37} 1341@subsection Wide_Character Encodings 1342 1343 1344GNAT allows wide character codes to appear in character and string 1345literals, and also optionally in identifiers, by means of the following 1346possible encoding schemes: 1347 1348 1349@table @asis 1350 1351@item @emph{Hex Coding} 1352 1353In this encoding, a wide character is represented by the following five 1354character sequence: 1355 1356@example 1357ESC a b c d 1358@end example 1359 1360where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 1361characters (using uppercase letters) of the wide character code. For 1362example, ESC A345 is used to represent the wide character with code 1363@code{16#A345#}. 1364This scheme is compatible with use of the full Wide_Character set. 1365 1366@item @emph{Upper-Half Coding} 1367 1368@geindex Upper-Half Coding 1369 1370The wide character with encoding @code{16#abcd#} where the upper bit is on 1371(in other words, 'a' is in the range 8-F) is represented as two bytes, 1372@code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control 1373character, but is not required to be in the upper half. This method can 1374be also used for shift-JIS or EUC, where the internal coding matches the 1375external coding. 1376 1377@item @emph{Shift JIS Coding} 1378 1379@geindex Shift JIS Coding 1380 1381A wide character is represented by a two-character sequence, 1382@code{16#ab#} and 1383@code{16#cd#}, with the restrictions described for upper-half encoding as 1384described above. The internal character code is the corresponding JIS 1385character according to the standard algorithm for Shift-JIS 1386conversion. Only characters defined in the JIS code set table can be 1387used with this encoding method. 1388 1389@item @emph{EUC Coding} 1390 1391@geindex EUC Coding 1392 1393A wide character is represented by a two-character sequence 1394@code{16#ab#} and 1395@code{16#cd#}, with both characters being in the upper half. The internal 1396character code is the corresponding JIS character according to the EUC 1397encoding algorithm. Only characters defined in the JIS code set table 1398can be used with this encoding method. 1399 1400@item @emph{UTF-8 Coding} 1401 1402A wide character is represented using 1403UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 140410646-1/Am.2. Depending on the character value, the representation 1405is a one, two, or three byte sequence: 1406 1407@example 140816#0000#-16#007f#: 2#0xxxxxxx# 140916#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 141016#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 1411@end example 1412 1413where the @code{xxx} bits correspond to the left-padded bits of the 141416-bit character value. Note that all lower half ASCII characters 1415are represented as ASCII bytes and all upper half characters and 1416other wide characters are represented as sequences of upper-half 1417(The full UTF-8 scheme allows for encoding 31-bit characters as 14186-byte sequences, and in the following section on wide wide 1419characters, the use of these sequences is documented). 1420 1421@item @emph{Brackets Coding} 1422 1423In this encoding, a wide character is represented by the following eight 1424character sequence: 1425 1426@example 1427[ " a b c d " ] 1428@end example 1429 1430where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 1431characters (using uppercase letters) of the wide character code. For 1432example, ['A345'] is used to represent the wide character with code 1433@code{16#A345#}. It is also possible (though not required) to use the 1434Brackets coding for upper half characters. For example, the code 1435@code{16#A3#} can be represented as @code{['A3']}. 1436 1437This scheme is compatible with use of the full Wide_Character set, 1438and is also the method used for wide character encoding in some standard 1439ACATS (Ada Conformity Assessment Test Suite) test suite distributions. 1440@end table 1441 1442@cartouche 1443@quotation Note 1444Some of these coding schemes do not permit the full use of the 1445Ada character set. For example, neither Shift JIS nor EUC allow the 1446use of the upper half of the Latin-1 set. 1447@end quotation 1448@end cartouche 1449 1450@node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation 1451@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{38}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{39} 1452@subsection Wide_Wide_Character Encodings 1453 1454 1455GNAT allows wide wide character codes to appear in character and string 1456literals, and also optionally in identifiers, by means of the following 1457possible encoding schemes: 1458 1459 1460@table @asis 1461 1462@item @emph{UTF-8 Coding} 1463 1464A wide character is represented using 1465UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 146610646-1/Am.2. Depending on the character value, the representation 1467of character codes with values greater than 16#FFFF# is a 1468is a four, five, or six byte sequence: 1469 1470@example 147116#01_0000#-16#10_FFFF#: 11110xxx 10xxxxxx 10xxxxxx 1472 10xxxxxx 147316#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx 1474 10xxxxxx 10xxxxxx 147516#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx 1476 10xxxxxx 10xxxxxx 10xxxxxx 1477@end example 1478 1479where the @code{xxx} bits correspond to the left-padded bits of the 148032-bit character value. 1481 1482@item @emph{Brackets Coding} 1483 1484In this encoding, a wide wide character is represented by the following ten or 1485twelve byte character sequence: 1486 1487@example 1488[ " a b c d e f " ] 1489[ " a b c d e f g h " ] 1490@end example 1491 1492where @code{a-h} are the six or eight hexadecimal 1493characters (using uppercase letters) of the wide wide character code. For 1494example, ["1F4567"] is used to represent the wide wide character with code 1495@code{16#001F_4567#}. 1496 1497This scheme is compatible with use of the full Wide_Wide_Character set, 1498and is also the method used for wide wide character encoding in some standard 1499ACATS (Ada Conformity Assessment Test Suite) test suite distributions. 1500@end table 1501 1502@node File Naming Topics and Utilities,Configuration Pragmas,Foreign Language Representation,The GNAT Compilation Model 1503@anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{3a}@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{24} 1504@section File Naming Topics and Utilities 1505 1506 1507GNAT has a default file naming scheme and also provides the user with 1508a high degree of control over how the names and extensions of the 1509source files correspond to the Ada compilation units that they contain. 1510 1511@menu 1512* File Naming Rules:: 1513* Using Other File Names:: 1514* Alternative File Naming Schemes:: 1515* Handling Arbitrary File Naming Conventions with gnatname:: 1516* File Name Krunching with gnatkr:: 1517* Renaming Files with gnatchop:: 1518 1519@end menu 1520 1521@node File Naming Rules,Using Other File Names,,File Naming Topics and Utilities 1522@anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{3b}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{3c} 1523@subsection File Naming Rules 1524 1525 1526The default file name is determined by the name of the unit that the 1527file contains. The name is formed by taking the full expanded name of 1528the unit and replacing the separating dots with hyphens and using 1529lowercase for all letters. 1530 1531An exception arises if the file name generated by the above rules starts 1532with one of the characters 1533@code{a}, @code{g}, @code{i}, or @code{s}, and the second character is a 1534minus. In this case, the character tilde is used in place 1535of the minus. The reason for this special rule is to avoid clashes with 1536the standard names for child units of the packages System, Ada, 1537Interfaces, and GNAT, which use the prefixes 1538@code{s-}, @code{a-}, @code{i-}, and @code{g-}, 1539respectively. 1540 1541The file extension is @code{.ads} for a spec and 1542@code{.adb} for a body. The following table shows some 1543examples of these rules. 1544 1545@quotation 1546 1547 1548@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 1549@item 1550 1551Source File 1552 1553@tab 1554 1555Ada Compilation Unit 1556 1557@item 1558 1559@code{main.ads} 1560 1561@tab 1562 1563Main (spec) 1564 1565@item 1566 1567@code{main.adb} 1568 1569@tab 1570 1571Main (body) 1572 1573@item 1574 1575@code{arith_functions.ads} 1576 1577@tab 1578 1579Arith_Functions (package spec) 1580 1581@item 1582 1583@code{arith_functions.adb} 1584 1585@tab 1586 1587Arith_Functions (package body) 1588 1589@item 1590 1591@code{func-spec.ads} 1592 1593@tab 1594 1595Func.Spec (child package spec) 1596 1597@item 1598 1599@code{func-spec.adb} 1600 1601@tab 1602 1603Func.Spec (child package body) 1604 1605@item 1606 1607@code{main-sub.adb} 1608 1609@tab 1610 1611Sub (subunit of Main) 1612 1613@item 1614 1615@code{a~bad.adb} 1616 1617@tab 1618 1619A.Bad (child package body) 1620 1621@end multitable 1622 1623@end quotation 1624 1625Following these rules can result in excessively long 1626file names if corresponding 1627unit names are long (for example, if child units or subunits are 1628heavily nested). An option is available to shorten such long file names 1629(called file name 'krunching'). This may be particularly useful when 1630programs being developed with GNAT are to be used on operating systems 1631with limited file name lengths. @ref{3d,,Using gnatkr}. 1632 1633Of course, no file shortening algorithm can guarantee uniqueness over 1634all possible unit names; if file name krunching is used, it is your 1635responsibility to ensure no name clashes occur. Alternatively you 1636can specify the exact file names that you want used, as described 1637in the next section. Finally, if your Ada programs are migrating from a 1638compiler with a different naming convention, you can use the gnatchop 1639utility to produce source files that follow the GNAT naming conventions. 1640(For details see @ref{1d,,Renaming Files with gnatchop}.) 1641 1642Note: in the case of Windows or Mac OS operating systems, case is not 1643significant. So for example on Windows if the canonical name is 1644@code{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead. 1645However, case is significant for other operating systems, so for example, 1646if you want to use other than canonically cased file names on a Unix system, 1647you need to follow the procedures described in the next section. 1648 1649@node Using Other File Names,Alternative File Naming Schemes,File Naming Rules,File Naming Topics and Utilities 1650@anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{3e}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{1c} 1651@subsection Using Other File Names 1652 1653 1654@geindex File names 1655 1656In the previous section, we have described the default rules used by 1657GNAT to determine the file name in which a given unit resides. It is 1658often convenient to follow these default rules, and if you follow them, 1659the compiler knows without being explicitly told where to find all 1660the files it needs. 1661 1662@geindex Source_File_Name pragma 1663 1664However, in some cases, particularly when a program is imported from 1665another Ada compiler environment, it may be more convenient for the 1666programmer to specify which file names contain which units. GNAT allows 1667arbitrary file names to be used by means of the Source_File_Name pragma. 1668The form of this pragma is as shown in the following examples: 1669 1670@example 1671pragma Source_File_Name (My_Utilities.Stacks, 1672 Spec_File_Name => "myutilst_a.ada"); 1673pragma Source_File_name (My_Utilities.Stacks, 1674 Body_File_Name => "myutilst.ada"); 1675@end example 1676 1677As shown in this example, the first argument for the pragma is the unit 1678name (in this example a child unit). The second argument has the form 1679of a named association. The identifier 1680indicates whether the file name is for a spec or a body; 1681the file name itself is given by a string literal. 1682 1683The source file name pragma is a configuration pragma, which means that 1684normally it will be placed in the @code{gnat.adc} 1685file used to hold configuration 1686pragmas that apply to a complete compilation environment. 1687For more details on how the @code{gnat.adc} file is created and used 1688see @ref{3f,,Handling of Configuration Pragmas}. 1689 1690@geindex gnat.adc 1691 1692GNAT allows completely arbitrary file names to be specified using the 1693source file name pragma. However, if the file name specified has an 1694extension other than @code{.ads} or @code{.adb} it is necessary to use 1695a special syntax when compiling the file. The name in this case must be 1696preceded by the special sequence @code{-x} followed by a space and the name 1697of the language, here @code{ada}, as in: 1698 1699@example 1700$ gcc -c -x ada peculiar_file_name.sim 1701@end example 1702 1703@code{gnatmake} handles non-standard file names in the usual manner (the 1704non-standard file name for the main program is simply used as the 1705argument to gnatmake). Note that if the extension is also non-standard, 1706then it must be included in the @code{gnatmake} command, it may not 1707be omitted. 1708 1709@node Alternative File Naming Schemes,Handling Arbitrary File Naming Conventions with gnatname,Using Other File Names,File Naming Topics and Utilities 1710@anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{41} 1711@subsection Alternative File Naming Schemes 1712 1713 1714@geindex File naming schemes 1715@geindex alternative 1716 1717@geindex File names 1718 1719The previous section described the use of the @code{Source_File_Name} 1720pragma to allow arbitrary names to be assigned to individual source files. 1721However, this approach requires one pragma for each file, and especially in 1722large systems can result in very long @code{gnat.adc} files, and also create 1723a maintenance problem. 1724 1725@geindex Source_File_Name pragma 1726 1727GNAT also provides a facility for specifying systematic file naming schemes 1728other than the standard default naming scheme previously described. An 1729alternative scheme for naming is specified by the use of 1730@code{Source_File_Name} pragmas having the following format: 1731 1732@example 1733pragma Source_File_Name ( 1734 Spec_File_Name => FILE_NAME_PATTERN 1735 [ , Casing => CASING_SPEC] 1736 [ , Dot_Replacement => STRING_LITERAL ] ); 1737 1738pragma Source_File_Name ( 1739 Body_File_Name => FILE_NAME_PATTERN 1740 [ , Casing => CASING_SPEC ] 1741 [ , Dot_Replacement => STRING_LITERAL ] ) ; 1742 1743pragma Source_File_Name ( 1744 Subunit_File_Name => FILE_NAME_PATTERN 1745 [ , Casing => CASING_SPEC ] 1746 [ , Dot_Replacement => STRING_LITERAL ] ) ; 1747 1748FILE_NAME_PATTERN ::= STRING_LITERAL 1749CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 1750@end example 1751 1752The @code{FILE_NAME_PATTERN} string shows how the file name is constructed. 1753It contains a single asterisk character, and the unit name is substituted 1754systematically for this asterisk. The optional parameter 1755@code{Casing} indicates 1756whether the unit name is to be all upper-case letters, all lower-case letters, 1757or mixed-case. If no 1758@code{Casing} parameter is used, then the default is all 1759lower-case. 1760 1761The optional @code{Dot_Replacement} string is used to replace any periods 1762that occur in subunit or child unit names. If no @code{Dot_Replacement} 1763argument is used then separating dots appear unchanged in the resulting 1764file name. 1765Although the above syntax indicates that the 1766@code{Casing} argument must appear 1767before the @code{Dot_Replacement} argument, but it 1768is also permissible to write these arguments in the opposite order. 1769 1770As indicated, it is possible to specify different naming schemes for 1771bodies, specs, and subunits. Quite often the rule for subunits is the 1772same as the rule for bodies, in which case, there is no need to give 1773a separate @code{Subunit_File_Name} rule, and in this case the 1774@code{Body_File_name} rule is used for subunits as well. 1775 1776The separate rule for subunits can also be used to implement the rather 1777unusual case of a compilation environment (e.g., a single directory) which 1778contains a subunit and a child unit with the same unit name. Although 1779both units cannot appear in the same partition, the Ada Reference Manual 1780allows (but does not require) the possibility of the two units coexisting 1781in the same environment. 1782 1783The file name translation works in the following steps: 1784 1785 1786@itemize * 1787 1788@item 1789If there is a specific @code{Source_File_Name} pragma for the given unit, 1790then this is always used, and any general pattern rules are ignored. 1791 1792@item 1793If there is a pattern type @code{Source_File_Name} pragma that applies to 1794the unit, then the resulting file name will be used if the file exists. If 1795more than one pattern matches, the latest one will be tried first, and the 1796first attempt resulting in a reference to a file that exists will be used. 1797 1798@item 1799If no pattern type @code{Source_File_Name} pragma that applies to the unit 1800for which the corresponding file exists, then the standard GNAT default 1801naming rules are used. 1802@end itemize 1803 1804As an example of the use of this mechanism, consider a commonly used scheme 1805in which file names are all lower case, with separating periods copied 1806unchanged to the resulting file name, and specs end with @code{.1.ada}, and 1807bodies end with @code{.2.ada}. GNAT will follow this scheme if the following 1808two pragmas appear: 1809 1810@example 1811pragma Source_File_Name 1812 (Spec_File_Name => ".1.ada"); 1813pragma Source_File_Name 1814 (Body_File_Name => ".2.ada"); 1815@end example 1816 1817The default GNAT scheme is actually implemented by providing the following 1818default pragmas internally: 1819 1820@example 1821pragma Source_File_Name 1822 (Spec_File_Name => ".ads", Dot_Replacement => "-"); 1823pragma Source_File_Name 1824 (Body_File_Name => ".adb", Dot_Replacement => "-"); 1825@end example 1826 1827Our final example implements a scheme typically used with one of the 1828Ada 83 compilers, where the separator character for subunits was '__' 1829(two underscores), specs were identified by adding @code{_.ADA}, bodies 1830by adding @code{.ADA}, and subunits by 1831adding @code{.SEP}. All file names were 1832upper case. Child units were not present of course since this was an 1833Ada 83 compiler, but it seems reasonable to extend this scheme to use 1834the same double underscore separator for child units. 1835 1836@example 1837pragma Source_File_Name 1838 (Spec_File_Name => "_.ADA", 1839 Dot_Replacement => "__", 1840 Casing = Uppercase); 1841pragma Source_File_Name 1842 (Body_File_Name => ".ADA", 1843 Dot_Replacement => "__", 1844 Casing = Uppercase); 1845pragma Source_File_Name 1846 (Subunit_File_Name => ".SEP", 1847 Dot_Replacement => "__", 1848 Casing = Uppercase); 1849@end example 1850 1851@geindex gnatname 1852 1853@node Handling Arbitrary File Naming Conventions with gnatname,File Name Krunching with gnatkr,Alternative File Naming Schemes,File Naming Topics and Utilities 1854@anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{42}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{43} 1855@subsection Handling Arbitrary File Naming Conventions with @code{gnatname} 1856 1857 1858@geindex File Naming Conventions 1859 1860@menu 1861* Arbitrary File Naming Conventions:: 1862* Running gnatname:: 1863* Switches for gnatname:: 1864* Examples of gnatname Usage:: 1865 1866@end menu 1867 1868@node Arbitrary File Naming Conventions,Running gnatname,,Handling Arbitrary File Naming Conventions with gnatname 1869@anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{44}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{45} 1870@subsubsection Arbitrary File Naming Conventions 1871 1872 1873The GNAT compiler must be able to know the source file name of a compilation 1874unit. When using the standard GNAT default file naming conventions 1875(@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler 1876does not need additional information. 1877 1878When the source file names do not follow the standard GNAT default file naming 1879conventions, the GNAT compiler must be given additional information through 1880a configuration pragmas file (@ref{25,,Configuration Pragmas}) 1881or a project file. 1882When the non-standard file naming conventions are well-defined, 1883a small number of pragmas @code{Source_File_Name} specifying a naming pattern 1884(@ref{41,,Alternative File Naming Schemes}) may be sufficient. However, 1885if the file naming conventions are irregular or arbitrary, a number 1886of pragma @code{Source_File_Name} for individual compilation units 1887must be defined. 1888To help maintain the correspondence between compilation unit names and 1889source file names within the compiler, 1890GNAT provides a tool @code{gnatname} to generate the required pragmas for a 1891set of files. 1892 1893@node Running gnatname,Switches for gnatname,Arbitrary File Naming Conventions,Handling Arbitrary File Naming Conventions with gnatname 1894@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{46}@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{47} 1895@subsubsection Running @code{gnatname} 1896 1897 1898The usual form of the @code{gnatname} command is: 1899 1900@example 1901$ gnatname [ switches ] naming_pattern [ naming_patterns ] 1902 [--and [ switches ] naming_pattern [ naming_patterns ]] 1903@end example 1904 1905All of the arguments are optional. If invoked without any argument, 1906@code{gnatname} will display its usage. 1907 1908When used with at least one naming pattern, @code{gnatname} will attempt to 1909find all the compilation units in files that follow at least one of the 1910naming patterns. To find these compilation units, 1911@code{gnatname} will use the GNAT compiler in syntax-check-only mode on all 1912regular files. 1913 1914One or several Naming Patterns may be given as arguments to @code{gnatname}. 1915Each Naming Pattern is enclosed between double quotes (or single 1916quotes on Windows). 1917A Naming Pattern is a regular expression similar to the wildcard patterns 1918used in file names by the Unix shells or the DOS prompt. 1919 1920@code{gnatname} may be called with several sections of directories/patterns. 1921Sections are separated by the switch @code{--and}. In each section, there must be 1922at least one pattern. If no directory is specified in a section, the current 1923directory (or the project directory if @code{-P} is used) is implied. 1924The options other that the directory switches and the patterns apply globally 1925even if they are in different sections. 1926 1927Examples of Naming Patterns are: 1928 1929@example 1930"*.[12].ada" 1931"*.ad[sb]*" 1932"body_*" "spec_*" 1933@end example 1934 1935For a more complete description of the syntax of Naming Patterns, 1936see the second kind of regular expressions described in @code{g-regexp.ads} 1937(the 'Glob' regular expressions). 1938 1939When invoked without the switch @code{-P}, @code{gnatname} will create a 1940configuration pragmas file @code{gnat.adc} in the current working directory, 1941with pragmas @code{Source_File_Name} for each file that contains a valid Ada 1942unit. 1943 1944@node Switches for gnatname,Examples of gnatname Usage,Running gnatname,Handling Arbitrary File Naming Conventions with gnatname 1945@anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{48}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{49} 1946@subsubsection Switches for @code{gnatname} 1947 1948 1949Switches for @code{gnatname} must precede any specified Naming Pattern. 1950 1951You may specify any of the following switches to @code{gnatname}: 1952 1953@geindex --version (gnatname) 1954 1955 1956@table @asis 1957 1958@item @code{--version} 1959 1960Display Copyright and version, then exit disregarding all other options. 1961@end table 1962 1963@geindex --help (gnatname) 1964 1965 1966@table @asis 1967 1968@item @code{--help} 1969 1970If @code{--version} was not used, display usage, then exit disregarding 1971all other options. 1972 1973@item @code{--subdirs=@emph{dir}} 1974 1975Real object, library or exec directories are subdirectories <dir> of the 1976specified ones. 1977 1978@item @code{--no-backup} 1979 1980Do not create a backup copy of an existing project file. 1981 1982@item @code{--and} 1983 1984Start another section of directories/patterns. 1985@end table 1986 1987@geindex -c (gnatname) 1988 1989 1990@table @asis 1991 1992@item @code{-c@emph{filename}} 1993 1994Create a configuration pragmas file @code{filename} (instead of the default 1995@code{gnat.adc}). 1996There may be zero, one or more space between @code{-c} and 1997@code{filename}. 1998@code{filename} may include directory information. @code{filename} must be 1999writable. There may be only one switch @code{-c}. 2000When a switch @code{-c} is 2001specified, no switch @code{-P} may be specified (see below). 2002@end table 2003 2004@geindex -d (gnatname) 2005 2006 2007@table @asis 2008 2009@item @code{-d@emph{dir}} 2010 2011Look for source files in directory @code{dir}. There may be zero, one or more 2012spaces between @code{-d} and @code{dir}. 2013@code{dir} may end with @code{/**}, that is it may be of the form 2014@code{root_dir/**}. In this case, the directory @code{root_dir} and all of its 2015subdirectories, recursively, have to be searched for sources. 2016When a switch @code{-d} 2017is specified, the current working directory will not be searched for source 2018files, unless it is explicitly specified with a @code{-d} 2019or @code{-D} switch. 2020Several switches @code{-d} may be specified. 2021If @code{dir} is a relative path, it is relative to the directory of 2022the configuration pragmas file specified with switch 2023@code{-c}, 2024or to the directory of the project file specified with switch 2025@code{-P} or, 2026if neither switch @code{-c} 2027nor switch @code{-P} are specified, it is relative to the 2028current working directory. The directory 2029specified with switch @code{-d} must exist and be readable. 2030@end table 2031 2032@geindex -D (gnatname) 2033 2034 2035@table @asis 2036 2037@item @code{-D@emph{filename}} 2038 2039Look for source files in all directories listed in text file @code{filename}. 2040There may be zero, one or more spaces between @code{-D} 2041and @code{filename}. 2042@code{filename} must be an existing, readable text file. 2043Each nonempty line in @code{filename} must be a directory. 2044Specifying switch @code{-D} is equivalent to specifying as many 2045switches @code{-d} as there are nonempty lines in 2046@code{file}. 2047 2048@item @code{-eL} 2049 2050Follow symbolic links when processing project files. 2051 2052@geindex -f (gnatname) 2053 2054@item @code{-f@emph{pattern}} 2055 2056Foreign patterns. Using this switch, it is possible to add sources of languages 2057other than Ada to the list of sources of a project file. 2058It is only useful if a -P switch is used. 2059For example, 2060 2061@example 2062gnatname -Pprj -f"*.c" "*.ada" 2063@end example 2064 2065will look for Ada units in all files with the @code{.ada} extension, 2066and will add to the list of file for project @code{prj.gpr} the C files 2067with extension @code{.c}. 2068 2069@geindex -h (gnatname) 2070 2071@item @code{-h} 2072 2073Output usage (help) information. The output is written to @code{stdout}. 2074 2075@geindex -P (gnatname) 2076 2077@item @code{-P@emph{proj}} 2078 2079Create or update project file @code{proj}. There may be zero, one or more space 2080between @code{-P} and @code{proj}. @code{proj} may include directory 2081information. @code{proj} must be writable. 2082There may be only one switch @code{-P}. 2083When a switch @code{-P} is specified, 2084no switch @code{-c} may be specified. 2085On all platforms, except on VMS, when @code{gnatname} is invoked for an 2086existing project file <proj>.gpr, a backup copy of the project file is created 2087in the project directory with file name <proj>.gpr.saved_x. 'x' is the first 2088non negative number that makes this backup copy a new file. 2089 2090@geindex -v (gnatname) 2091 2092@item @code{-v} 2093 2094Verbose mode. Output detailed explanation of behavior to @code{stdout}. 2095This includes name of the file written, the name of the directories to search 2096and, for each file in those directories whose name matches at least one of 2097the Naming Patterns, an indication of whether the file contains a unit, 2098and if so the name of the unit. 2099@end table 2100 2101@geindex -v -v (gnatname) 2102 2103 2104@table @asis 2105 2106@item @code{-v -v} 2107 2108Very Verbose mode. In addition to the output produced in verbose mode, 2109for each file in the searched directories whose name matches none of 2110the Naming Patterns, an indication is given that there is no match. 2111 2112@geindex -x (gnatname) 2113 2114@item @code{-x@emph{pattern}} 2115 2116Excluded patterns. Using this switch, it is possible to exclude some files 2117that would match the name patterns. For example, 2118 2119@example 2120gnatname -x "*_nt.ada" "*.ada" 2121@end example 2122 2123will look for Ada units in all files with the @code{.ada} extension, 2124except those whose names end with @code{_nt.ada}. 2125@end table 2126 2127@node Examples of gnatname Usage,,Switches for gnatname,Handling Arbitrary File Naming Conventions with gnatname 2128@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{4a}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{4b} 2129@subsubsection Examples of @code{gnatname} Usage 2130 2131 2132@example 2133$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" 2134@end example 2135 2136In this example, the directory @code{/home/me} must already exist 2137and be writable. In addition, the directory 2138@code{/home/me/sources} (specified by 2139@code{-d sources}) must exist and be readable. 2140 2141Note the optional spaces after @code{-c} and @code{-d}. 2142 2143@example 2144$ gnatname -P/home/me/proj -x "*_nt_body.ada" 2145-dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" 2146@end example 2147 2148Note that several switches @code{-d} may be used, 2149even in conjunction with one or several switches 2150@code{-D}. Several Naming Patterns and one excluded pattern 2151are used in this example. 2152 2153@node File Name Krunching with gnatkr,Renaming Files with gnatchop,Handling Arbitrary File Naming Conventions with gnatname,File Naming Topics and Utilities 2154@anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{4c}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{4d} 2155@subsection File Name Krunching with @code{gnatkr} 2156 2157 2158@geindex gnatkr 2159 2160This section discusses the method used by the compiler to shorten 2161the default file names chosen for Ada units so that they do not 2162exceed the maximum length permitted. It also describes the 2163@code{gnatkr} utility that can be used to determine the result of 2164applying this shortening. 2165 2166@menu 2167* About gnatkr:: 2168* Using gnatkr:: 2169* Krunching Method:: 2170* Examples of gnatkr Usage:: 2171 2172@end menu 2173 2174@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr 2175@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{4e}@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{4f} 2176@subsubsection About @code{gnatkr} 2177 2178 2179The default file naming rule in GNAT 2180is that the file name must be derived from 2181the unit name. The exact default rule is as follows: 2182 2183 2184@itemize * 2185 2186@item 2187Take the unit name and replace all dots by hyphens. 2188 2189@item 2190If such a replacement occurs in the 2191second character position of a name, and the first character is 2192@code{a}, @code{g}, @code{s}, or @code{i}, 2193then replace the dot by the character 2194@code{~} (tilde) 2195instead of a minus. 2196 2197The reason for this exception is to avoid clashes 2198with the standard names for children of System, Ada, Interfaces, 2199and GNAT, which use the prefixes 2200@code{s-}, @code{a-}, @code{i-}, and @code{g-}, 2201respectively. 2202@end itemize 2203 2204The @code{-gnatk@emph{nn}} 2205switch of the compiler activates a 'krunching' 2206circuit that limits file names to nn characters (where nn is a decimal 2207integer). 2208 2209The @code{gnatkr} utility can be used to determine the krunched name for 2210a given file, when krunched to a specified maximum length. 2211 2212@node Using gnatkr,Krunching Method,About gnatkr,File Name Krunching with gnatkr 2213@anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{50}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{3d} 2214@subsubsection Using @code{gnatkr} 2215 2216 2217The @code{gnatkr} command has the form: 2218 2219@example 2220$ gnatkr name [ length ] 2221@end example 2222 2223@code{name} is the uncrunched file name, derived from the name of the unit 2224in the standard manner described in the previous section (i.e., in particular 2225all dots are replaced by hyphens). The file name may or may not have an 2226extension (defined as a suffix of the form period followed by arbitrary 2227characters other than period). If an extension is present then it will 2228be preserved in the output. For example, when krunching @code{hellofile.ads} 2229to eight characters, the result will be hellofil.ads. 2230 2231Note: for compatibility with previous versions of @code{gnatkr} dots may 2232appear in the name instead of hyphens, but the last dot will always be 2233taken as the start of an extension. So if @code{gnatkr} is given an argument 2234such as @code{Hello.World.adb} it will be treated exactly as if the first 2235period had been a hyphen, and for example krunching to eight characters 2236gives the result @code{hellworl.adb}. 2237 2238Note that the result is always all lower case. 2239Characters of the other case are folded as required. 2240 2241@code{length} represents the length of the krunched name. The default 2242when no argument is given is 8 characters. A length of zero stands for 2243unlimited, in other words do not chop except for system files where the 2244implied crunching length is always eight characters. 2245 2246The output is the krunched name. The output has an extension only if the 2247original argument was a file name with an extension. 2248 2249@node Krunching Method,Examples of gnatkr Usage,Using gnatkr,File Name Krunching with gnatkr 2250@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{52} 2251@subsubsection Krunching Method 2252 2253 2254The initial file name is determined by the name of the unit that the file 2255contains. The name is formed by taking the full expanded name of the 2256unit and replacing the separating dots with hyphens and 2257using lowercase 2258for all letters, except that a hyphen in the second character position is 2259replaced by a tilde if the first character is 2260@code{a}, @code{i}, @code{g}, or @code{s}. 2261The extension is @code{.ads} for a 2262spec and @code{.adb} for a body. 2263Krunching does not affect the extension, but the file name is shortened to 2264the specified length by following these rules: 2265 2266 2267@itemize * 2268 2269@item 2270The name is divided into segments separated by hyphens, tildes or 2271underscores and all hyphens, tildes, and underscores are 2272eliminated. If this leaves the name short enough, we are done. 2273 2274@item 2275If the name is too long, the longest segment is located (left-most 2276if there are two of equal length), and shortened by dropping 2277its last character. This is repeated until the name is short enough. 2278 2279As an example, consider the krunching of @code{our-strings-wide_fixed.adb} 2280to fit the name into 8 characters as required by some operating systems: 2281 2282@example 2283our-strings-wide_fixed 22 2284our strings wide fixed 19 2285our string wide fixed 18 2286our strin wide fixed 17 2287our stri wide fixed 16 2288our stri wide fixe 15 2289our str wide fixe 14 2290our str wid fixe 13 2291our str wid fix 12 2292ou str wid fix 11 2293ou st wid fix 10 2294ou st wi fix 9 2295ou st wi fi 8 2296Final file name: oustwifi.adb 2297@end example 2298 2299@item 2300The file names for all predefined units are always krunched to eight 2301characters. The krunching of these predefined units uses the following 2302special prefix replacements: 2303 2304 2305@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 2306@item 2307 2308Prefix 2309 2310@tab 2311 2312Replacement 2313 2314@item 2315 2316@code{ada-} 2317 2318@tab 2319 2320@code{a-} 2321 2322@item 2323 2324@code{gnat-} 2325 2326@tab 2327 2328@code{g-} 2329 2330@item 2331 2332@code{interfac es-} 2333 2334@tab 2335 2336@code{i-} 2337 2338@item 2339 2340@code{system-} 2341 2342@tab 2343 2344@code{s-} 2345 2346@end multitable 2347 2348 2349These system files have a hyphen in the second character position. That 2350is why normal user files replace such a character with a 2351tilde, to avoid confusion with system file names. 2352 2353As an example of this special rule, consider 2354@code{ada-strings-wide_fixed.adb}, which gets krunched as follows: 2355 2356@example 2357ada-strings-wide_fixed 22 2358a- strings wide fixed 18 2359a- string wide fixed 17 2360a- strin wide fixed 16 2361a- stri wide fixed 15 2362a- stri wide fixe 14 2363a- str wide fixe 13 2364a- str wid fixe 12 2365a- str wid fix 11 2366a- st wid fix 10 2367a- st wi fix 9 2368a- st wi fi 8 2369Final file name: a-stwifi.adb 2370@end example 2371@end itemize 2372 2373Of course no file shortening algorithm can guarantee uniqueness over all 2374possible unit names, and if file name krunching is used then it is your 2375responsibility to ensure that no name clashes occur. The utility 2376program @code{gnatkr} is supplied for conveniently determining the 2377krunched name of a file. 2378 2379@node Examples of gnatkr Usage,,Krunching Method,File Name Krunching with gnatkr 2380@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{53}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{54} 2381@subsubsection Examples of @code{gnatkr} Usage 2382 2383 2384@example 2385$ gnatkr very_long_unit_name.ads --> velounna.ads 2386$ gnatkr grandparent-parent-child.ads --> grparchi.ads 2387$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads 2388$ gnatkr grandparent-parent-child --> grparchi 2389$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads 2390$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads 2391@end example 2392 2393@node Renaming Files with gnatchop,,File Name Krunching with gnatkr,File Naming Topics and Utilities 2394@anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{55}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{1d} 2395@subsection Renaming Files with @code{gnatchop} 2396 2397 2398@geindex gnatchop 2399 2400This section discusses how to handle files with multiple units by using 2401the @code{gnatchop} utility. This utility is also useful in renaming 2402files to meet the standard GNAT default file naming conventions. 2403 2404@menu 2405* Handling Files with Multiple Units:: 2406* Operating gnatchop in Compilation Mode:: 2407* Command Line for gnatchop:: 2408* Switches for gnatchop:: 2409* Examples of gnatchop Usage:: 2410 2411@end menu 2412 2413@node Handling Files with Multiple Units,Operating gnatchop in Compilation Mode,,Renaming Files with gnatchop 2414@anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{56}@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{57} 2415@subsubsection Handling Files with Multiple Units 2416 2417 2418The basic compilation model of GNAT requires that a file submitted to the 2419compiler have only one unit and there be a strict correspondence 2420between the file name and the unit name. 2421 2422If you want to keep your files with multiple units, 2423perhaps to maintain compatibility with some other Ada compilation system, 2424you can use @code{gnatname} to generate or update your project files. 2425Generated or modified project files can be processed by GNAT. 2426 2427See @ref{42,,Handling Arbitrary File Naming Conventions with gnatname} 2428for more details on how to use @cite{gnatname}. 2429 2430Alternatively, if you want to permanently restructure a set of 'foreign' 2431files so that they match the GNAT rules, and do the remaining development 2432using the GNAT structure, you can simply use @code{gnatchop} once, generate the 2433new set of files and work with them from that point on. 2434 2435Note that if your file containing multiple units starts with a byte order 2436mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop 2437will each start with a copy of this BOM, meaning that they can be compiled 2438automatically in UTF-8 mode without needing to specify an explicit encoding. 2439 2440@node Operating gnatchop in Compilation Mode,Command Line for gnatchop,Handling Files with Multiple Units,Renaming Files with gnatchop 2441@anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{58}@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{59} 2442@subsubsection Operating gnatchop in Compilation Mode 2443 2444 2445The basic function of @code{gnatchop} is to take a file with multiple units 2446and split it into separate files. The boundary between files is reasonably 2447clear, except for the issue of comments and pragmas. In default mode, the 2448rule is that any pragmas between units belong to the previous unit, except 2449that configuration pragmas always belong to the following unit. Any comments 2450belong to the following unit. These rules 2451almost always result in the right choice of 2452the split point without needing to mark it explicitly and most users will 2453find this default to be what they want. In this default mode it is incorrect to 2454submit a file containing only configuration pragmas, or one that ends in 2455configuration pragmas, to @code{gnatchop}. 2456 2457However, using a special option to activate 'compilation mode', 2458@code{gnatchop} 2459can perform another function, which is to provide exactly the semantics 2460required by the RM for handling of configuration pragmas in a compilation. 2461In the absence of configuration pragmas (at the main file level), this 2462option has no effect, but it causes such configuration pragmas to be handled 2463in a quite different manner. 2464 2465First, in compilation mode, if @code{gnatchop} is given a file that consists of 2466only configuration pragmas, then this file is appended to the 2467@code{gnat.adc} file in the current directory. This behavior provides 2468the required behavior described in the RM for the actions to be taken 2469on submitting such a file to the compiler, namely that these pragmas 2470should apply to all subsequent compilations in the same compilation 2471environment. Using GNAT, the current directory, possibly containing a 2472@code{gnat.adc} file is the representation 2473of a compilation environment. For more information on the 2474@code{gnat.adc} file, see @ref{3f,,Handling of Configuration Pragmas}. 2475 2476Second, in compilation mode, if @code{gnatchop} 2477is given a file that starts with 2478configuration pragmas, and contains one or more units, then these 2479configuration pragmas are prepended to each of the chopped files. This 2480behavior provides the required behavior described in the RM for the 2481actions to be taken on compiling such a file, namely that the pragmas 2482apply to all units in the compilation, but not to subsequently compiled 2483units. 2484 2485Finally, if configuration pragmas appear between units, they are appended 2486to the previous unit. This results in the previous unit being illegal, 2487since the compiler does not accept configuration pragmas that follow 2488a unit. This provides the required RM behavior that forbids configuration 2489pragmas other than those preceding the first compilation unit of a 2490compilation. 2491 2492For most purposes, @code{gnatchop} will be used in default mode. The 2493compilation mode described above is used only if you need exactly 2494accurate behavior with respect to compilations, and you have files 2495that contain multiple units and configuration pragmas. In this 2496circumstance the use of @code{gnatchop} with the compilation mode 2497switch provides the required behavior, and is for example the mode 2498in which GNAT processes the ACVC tests. 2499 2500@node Command Line for gnatchop,Switches for gnatchop,Operating gnatchop in Compilation Mode,Renaming Files with gnatchop 2501@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{5a}@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{5b} 2502@subsubsection Command Line for @code{gnatchop} 2503 2504 2505The @code{gnatchop} command has the form: 2506 2507@example 2508$ gnatchop switches file_name [file_name ...] 2509 [directory] 2510@end example 2511 2512The only required argument is the file name of the file to be chopped. 2513There are no restrictions on the form of this file name. The file itself 2514contains one or more Ada units, in normal GNAT format, concatenated 2515together. As shown, more than one file may be presented to be chopped. 2516 2517When run in default mode, @code{gnatchop} generates one output file in 2518the current directory for each unit in each of the files. 2519 2520@code{directory}, if specified, gives the name of the directory to which 2521the output files will be written. If it is not specified, all files are 2522written to the current directory. 2523 2524For example, given a 2525file called @code{hellofiles} containing 2526 2527@example 2528procedure Hello; 2529 2530with Ada.Text_IO; use Ada.Text_IO; 2531procedure Hello is 2532begin 2533 Put_Line ("Hello"); 2534end Hello; 2535@end example 2536 2537the command 2538 2539@example 2540$ gnatchop hellofiles 2541@end example 2542 2543generates two files in the current directory, one called 2544@code{hello.ads} containing the single line that is the procedure spec, 2545and the other called @code{hello.adb} containing the remaining text. The 2546original file is not affected. The generated files can be compiled in 2547the normal manner. 2548 2549When gnatchop is invoked on a file that is empty or that contains only empty 2550lines and/or comments, gnatchop will not fail, but will not produce any 2551new sources. 2552 2553For example, given a 2554file called @code{toto.txt} containing 2555 2556@example 2557-- Just a comment 2558@end example 2559 2560the command 2561 2562@example 2563$ gnatchop toto.txt 2564@end example 2565 2566will not produce any new file and will result in the following warnings: 2567 2568@example 2569toto.txt:1:01: warning: empty file, contains no compilation units 2570no compilation units found 2571no source files written 2572@end example 2573 2574@node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop 2575@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{5c}@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{5d} 2576@subsubsection Switches for @code{gnatchop} 2577 2578 2579@code{gnatchop} recognizes the following switches: 2580 2581@geindex --version (gnatchop) 2582 2583 2584@table @asis 2585 2586@item @code{--version} 2587 2588Display Copyright and version, then exit disregarding all other options. 2589@end table 2590 2591@geindex --help (gnatchop) 2592 2593 2594@table @asis 2595 2596@item @code{--help} 2597 2598If @code{--version} was not used, display usage, then exit disregarding 2599all other options. 2600@end table 2601 2602@geindex -c (gnatchop) 2603 2604 2605@table @asis 2606 2607@item @code{-c} 2608 2609Causes @code{gnatchop} to operate in compilation mode, in which 2610configuration pragmas are handled according to strict RM rules. See 2611previous section for a full description of this mode. 2612 2613@item @code{-gnat@emph{xxx}} 2614 2615This passes the given @code{-gnat@emph{xxx}} switch to @code{gnat} which is 2616used to parse the given file. Not all @emph{xxx} options make sense, 2617but for example, the use of @code{-gnati2} allows @code{gnatchop} to 2618process a source file that uses Latin-2 coding for identifiers. 2619 2620@item @code{-h} 2621 2622Causes @code{gnatchop} to generate a brief help summary to the standard 2623output file showing usage information. 2624@end table 2625 2626@geindex -k (gnatchop) 2627 2628 2629@table @asis 2630 2631@item @code{-k@emph{mm}} 2632 2633Limit generated file names to the specified number @code{mm} 2634of characters. 2635This is useful if the 2636resulting set of files is required to be interoperable with systems 2637which limit the length of file names. 2638No space is allowed between the @code{-k} and the numeric value. The numeric 2639value may be omitted in which case a default of @code{-k8}, 2640suitable for use 2641with DOS-like file systems, is used. If no @code{-k} switch 2642is present then 2643there is no limit on the length of file names. 2644@end table 2645 2646@geindex -p (gnatchop) 2647 2648 2649@table @asis 2650 2651@item @code{-p} 2652 2653Causes the file modification time stamp of the input file to be 2654preserved and used for the time stamp of the output file(s). This may be 2655useful for preserving coherency of time stamps in an environment where 2656@code{gnatchop} is used as part of a standard build process. 2657@end table 2658 2659@geindex -q (gnatchop) 2660 2661 2662@table @asis 2663 2664@item @code{-q} 2665 2666Causes output of informational messages indicating the set of generated 2667files to be suppressed. Warnings and error messages are unaffected. 2668@end table 2669 2670@geindex -r (gnatchop) 2671 2672@geindex Source_Reference pragmas 2673 2674 2675@table @asis 2676 2677@item @code{-r} 2678 2679Generate @code{Source_Reference} pragmas. Use this switch if the output 2680files are regarded as temporary and development is to be done in terms 2681of the original unchopped file. This switch causes 2682@code{Source_Reference} pragmas to be inserted into each of the 2683generated files to refers back to the original file name and line number. 2684The result is that all error messages refer back to the original 2685unchopped file. 2686In addition, the debugging information placed into the object file (when 2687the @code{-g} switch of @code{gcc} or @code{gnatmake} is 2688specified) 2689also refers back to this original file so that tools like profilers and 2690debuggers will give information in terms of the original unchopped file. 2691 2692If the original file to be chopped itself contains 2693a @code{Source_Reference} 2694pragma referencing a third file, then gnatchop respects 2695this pragma, and the generated @code{Source_Reference} pragmas 2696in the chopped file refer to the original file, with appropriate 2697line numbers. This is particularly useful when @code{gnatchop} 2698is used in conjunction with @code{gnatprep} to compile files that 2699contain preprocessing statements and multiple units. 2700@end table 2701 2702@geindex -v (gnatchop) 2703 2704 2705@table @asis 2706 2707@item @code{-v} 2708 2709Causes @code{gnatchop} to operate in verbose mode. The version 2710number and copyright notice are output, as well as exact copies of 2711the gnat1 commands spawned to obtain the chop control information. 2712@end table 2713 2714@geindex -w (gnatchop) 2715 2716 2717@table @asis 2718 2719@item @code{-w} 2720 2721Overwrite existing file names. Normally @code{gnatchop} regards it as a 2722fatal error if there is already a file with the same name as a 2723file it would otherwise output, in other words if the files to be 2724chopped contain duplicated units. This switch bypasses this 2725check, and causes all but the last instance of such duplicated 2726units to be skipped. 2727@end table 2728 2729@geindex --GCC= (gnatchop) 2730 2731 2732@table @asis 2733 2734@item @code{--GCC=@emph{xxxx}} 2735 2736Specify the path of the GNAT parser to be used. When this switch is used, 2737no attempt is made to add the prefix to the GNAT parser executable. 2738@end table 2739 2740@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop 2741@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{5e}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{5f} 2742@subsubsection Examples of @code{gnatchop} Usage 2743 2744 2745@example 2746$ gnatchop -w hello_s.ada prerelease/files 2747@end example 2748 2749Chops the source file @code{hello_s.ada}. The output files will be 2750placed in the directory @code{prerelease/files}, 2751overwriting any 2752files with matching names in that directory (no files in the current 2753directory are modified). 2754 2755@example 2756$ gnatchop archive 2757@end example 2758 2759Chops the source file @code{archive} 2760into the current directory. One 2761useful application of @code{gnatchop} is in sending sets of sources 2762around, for example in email messages. The required sources are simply 2763concatenated (for example, using a Unix @code{cat} 2764command), and then 2765@code{gnatchop} is used at the other end to reconstitute the original 2766file names. 2767 2768@example 2769$ gnatchop file1 file2 file3 direc 2770@end example 2771 2772Chops all units in files @code{file1}, @code{file2}, @code{file3}, placing 2773the resulting files in the directory @code{direc}. Note that if any units 2774occur more than once anywhere within this set of files, an error message 2775is generated, and no files are written. To override this check, use the 2776@code{-w} switch, 2777in which case the last occurrence in the last file will 2778be the one that is output, and earlier duplicate occurrences for a given 2779unit will be skipped. 2780 2781@node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model 2782@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{60}@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{25} 2783@section Configuration Pragmas 2784 2785 2786@geindex Configuration pragmas 2787 2788@geindex Pragmas 2789@geindex configuration 2790 2791Configuration pragmas include those pragmas described as 2792such in the Ada Reference Manual, as well as 2793implementation-dependent pragmas that are configuration pragmas. 2794See the @code{Implementation_Defined_Pragmas} chapter in the 2795@cite{GNAT_Reference_Manual} for details on these 2796additional GNAT-specific configuration pragmas. 2797Most notably, the pragma @code{Source_File_Name}, which allows 2798specifying non-default names for source files, is a configuration 2799pragma. The following is a complete list of configuration pragmas 2800recognized by GNAT: 2801 2802@example 2803Ada_83 2804Ada_95 2805Ada_05 2806Ada_2005 2807Ada_12 2808Ada_2012 2809Allow_Integer_Address 2810Annotate 2811Assertion_Policy 2812Assume_No_Invalid_Values 2813C_Pass_By_Copy 2814Check_Float_Overflow 2815Check_Name 2816Check_Policy 2817Compile_Time_Error 2818Compile_Time_Warning 2819Compiler_Unit 2820Compiler_Unit_Warning 2821Component_Alignment 2822Convention_Identifier 2823Debug_Policy 2824Detect_Blocking 2825Default_Scalar_Storage_Order 2826Default_Storage_Pool 2827Disable_Atomic_Synchronization 2828Discard_Names 2829Elaboration_Checks 2830Eliminate 2831Enable_Atomic_Synchronization 2832Extend_System 2833Extensions_Allowed 2834External_Name_Casing 2835Fast_Math 2836Favor_Top_Level 2837Ignore_Pragma 2838Implicit_Packing 2839Initialize_Scalars 2840Interrupt_State 2841License 2842Locking_Policy 2843No_Component_Reordering 2844No_Heap_Finalization 2845No_Run_Time 2846No_Strict_Aliasing 2847Normalize_Scalars 2848Optimize_Alignment 2849Overflow_Mode 2850Overriding_Renamings 2851Partition_Elaboration_Policy 2852Persistent_BSS 2853Prefix_Exception_Messages 2854Priority_Specific_Dispatching 2855Profile 2856Profile_Warnings 2857Propagate_Exceptions 2858Queuing_Policy 2859Rational 2860Ravenscar 2861Rename_Pragma 2862Restricted_Run_Time 2863Restrictions 2864Restrictions_Warnings 2865Reviewable 2866Short_Circuit_And_Or 2867Short_Descriptors 2868Source_File_Name 2869Source_File_Name_Project 2870SPARK_Mode 2871Style_Checks 2872Suppress 2873Suppress_Exception_Locations 2874Task_Dispatching_Policy 2875Unevaluated_Use_Of_Old 2876Universal_Data 2877Unsuppress 2878Use_VADS_Size 2879Validity_Checks 2880Warning_As_Error 2881Warnings 2882Wide_Character_Encoding 2883@end example 2884 2885@menu 2886* Handling of Configuration Pragmas:: 2887* The Configuration Pragmas Files:: 2888 2889@end menu 2890 2891@node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas 2892@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{61}@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{3f} 2893@subsection Handling of Configuration Pragmas 2894 2895 2896Configuration pragmas may either appear at the start of a compilation 2897unit, or they can appear in a configuration pragma file to apply to 2898all compilations performed in a given compilation environment. 2899 2900GNAT also provides the @code{gnatchop} utility to provide an automatic 2901way to handle configuration pragmas following the semantics for 2902compilations (that is, files with multiple units), described in the RM. 2903See @ref{58,,Operating gnatchop in Compilation Mode} for details. 2904However, for most purposes, it will be more convenient to edit the 2905@code{gnat.adc} file that contains configuration pragmas directly, 2906as described in the following section. 2907 2908In the case of @code{Restrictions} pragmas appearing as configuration 2909pragmas in individual compilation units, the exact handling depends on 2910the type of restriction. 2911 2912Restrictions that require partition-wide consistency (like 2913@code{No_Tasking}) are 2914recognized wherever they appear 2915and can be freely inherited, e.g. from a @emph{with}ed unit to the @emph{with}ing 2916unit. This makes sense since the binder will in any case insist on seeing 2917consistent use, so any unit not conforming to any restrictions that are 2918anywhere in the partition will be rejected, and you might as well find 2919that out at compile time rather than at bind time. 2920 2921For restrictions that do not require partition-wide consistency, e.g. 2922SPARK or No_Implementation_Attributes, in general the restriction applies 2923only to the unit in which the pragma appears, and not to any other units. 2924 2925The exception is No_Elaboration_Code which always applies to the entire 2926object file from a compilation, i.e. to the body, spec, and all subunits. 2927This restriction can be specified in a configuration pragma file, or it 2928can be on the body and/or the spec (in eithe case it applies to all the 2929relevant units). It can appear on a subunit only if it has previously 2930appeared in the body of spec. 2931 2932@node The Configuration Pragmas Files,,Handling of Configuration Pragmas,Configuration Pragmas 2933@anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{62}@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{63} 2934@subsection The Configuration Pragmas Files 2935 2936 2937@geindex gnat.adc 2938 2939In GNAT a compilation environment is defined by the current 2940directory at the time that a compile command is given. This current 2941directory is searched for a file whose name is @code{gnat.adc}. If 2942this file is present, it is expected to contain one or more 2943configuration pragmas that will be applied to the current compilation. 2944However, if the switch @code{-gnatA} is used, @code{gnat.adc} is not 2945considered. When taken into account, @code{gnat.adc} is added to the 2946dependencies, so that if @code{gnat.adc} is modified later, an invocation of 2947@code{gnatmake} will recompile the source. 2948 2949Configuration pragmas may be entered into the @code{gnat.adc} file 2950either by running @code{gnatchop} on a source file that consists only of 2951configuration pragmas, or more conveniently by direct editing of the 2952@code{gnat.adc} file, which is a standard format source file. 2953 2954Besides @code{gnat.adc}, additional files containing configuration 2955pragmas may be applied to the current compilation using the switch 2956@code{-gnatec=@emph{path}} where @code{path} must designate an existing file that 2957contains only configuration pragmas. These configuration pragmas are 2958in addition to those found in @code{gnat.adc} (provided @code{gnat.adc} 2959is present and switch @code{-gnatA} is not used). 2960 2961It is allowable to specify several switches @code{-gnatec=}, all of which 2962will be taken into account. 2963 2964Files containing configuration pragmas specified with switches 2965@code{-gnatec=} are added to the dependencies, unless they are 2966temporary files. A file is considered temporary if its name ends in 2967@code{.tmp} or @code{.TMP}. Certain tools follow this naming 2968convention because they pass information to @code{gcc} via 2969temporary files that are immediately deleted; it doesn't make sense to 2970depend on a file that no longer exists. Such tools include 2971@code{gprbuild}, @code{gnatmake}, and @code{gnatcheck}. 2972 2973By default, configuration pragma files are stored by their absolute paths in 2974ALI files. You can use the @code{-gnateb} switch in order to store them by 2975their basename instead. 2976 2977If you are using project file, a separate mechanism is provided using 2978project attributes. 2979 2980@c --Comment 2981@c See :ref:`Specifying_Configuration_Pragmas` for more details. 2982 2983@node Generating Object Files,Source Dependencies,Configuration Pragmas,The GNAT Compilation Model 2984@anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{26}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{64} 2985@section Generating Object Files 2986 2987 2988An Ada program consists of a set of source files, and the first step in 2989compiling the program is to generate the corresponding object files. 2990These are generated by compiling a subset of these source files. 2991The files you need to compile are the following: 2992 2993 2994@itemize * 2995 2996@item 2997If a package spec has no body, compile the package spec to produce the 2998object file for the package. 2999 3000@item 3001If a package has both a spec and a body, compile the body to produce the 3002object file for the package. The source file for the package spec need 3003not be compiled in this case because there is only one object file, which 3004contains the code for both the spec and body of the package. 3005 3006@item 3007For a subprogram, compile the subprogram body to produce the object file 3008for the subprogram. The spec, if one is present, is as usual in a 3009separate file, and need not be compiled. 3010@end itemize 3011 3012@geindex Subunits 3013 3014 3015@itemize * 3016 3017@item 3018In the case of subunits, only compile the parent unit. A single object 3019file is generated for the entire subunit tree, which includes all the 3020subunits. 3021 3022@item 3023Compile child units independently of their parent units 3024(though, of course, the spec of all the ancestor unit must be present in order 3025to compile a child unit). 3026 3027@geindex Generics 3028 3029@item 3030Compile generic units in the same manner as any other units. The object 3031files in this case are small dummy files that contain at most the 3032flag used for elaboration checking. This is because GNAT always handles generic 3033instantiation by means of macro expansion. However, it is still necessary to 3034compile generic units, for dependency checking and elaboration purposes. 3035@end itemize 3036 3037The preceding rules describe the set of files that must be compiled to 3038generate the object files for a program. Each object file has the same 3039name as the corresponding source file, except that the extension is 3040@code{.o} as usual. 3041 3042You may wish to compile other files for the purpose of checking their 3043syntactic and semantic correctness. For example, in the case where a 3044package has a separate spec and body, you would not normally compile the 3045spec. However, it is convenient in practice to compile the spec to make 3046sure it is error-free before compiling clients of this spec, because such 3047compilations will fail if there is an error in the spec. 3048 3049GNAT provides an option for compiling such files purely for the 3050purposes of checking correctness; such compilations are not required as 3051part of the process of building a program. To compile a file in this 3052checking mode, use the @code{-gnatc} switch. 3053 3054@node Source Dependencies,The Ada Library Information Files,Generating Object Files,The GNAT Compilation Model 3055@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{27} 3056@section Source Dependencies 3057 3058 3059A given object file clearly depends on the source file which is compiled 3060to produce it. Here we are using "depends" in the sense of a typical 3061@code{make} utility; in other words, an object file depends on a source 3062file if changes to the source file require the object file to be 3063recompiled. 3064In addition to this basic dependency, a given object may depend on 3065additional source files as follows: 3066 3067 3068@itemize * 3069 3070@item 3071If a file being compiled @emph{with}s a unit @code{X}, the object file 3072depends on the file containing the spec of unit @code{X}. This includes 3073files that are @emph{with}ed implicitly either because they are parents 3074of @emph{with}ed child units or they are run-time units required by the 3075language constructs used in a particular unit. 3076 3077@item 3078If a file being compiled instantiates a library level generic unit, the 3079object file depends on both the spec and body files for this generic 3080unit. 3081 3082@item 3083If a file being compiled instantiates a generic unit defined within a 3084package, the object file depends on the body file for the package as 3085well as the spec file. 3086@end itemize 3087 3088@geindex Inline 3089 3090@geindex -gnatn switch 3091 3092 3093@itemize * 3094 3095@item 3096If a file being compiled contains a call to a subprogram for which 3097pragma @code{Inline} applies and inlining is activated with the 3098@code{-gnatn} switch, the object file depends on the file containing the 3099body of this subprogram as well as on the file containing the spec. Note 3100that for inlining to actually occur as a result of the use of this switch, 3101it is necessary to compile in optimizing mode. 3102 3103@geindex -gnatN switch 3104 3105The use of @code{-gnatN} activates inlining optimization 3106that is performed by the front end of the compiler. This inlining does 3107not require that the code generation be optimized. Like @code{-gnatn}, 3108the use of this switch generates additional dependencies. 3109 3110When using a gcc-based back end (in practice this means using any version 3111of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of 3112@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred. 3113Historically front end inlining was more extensive than the gcc back end 3114inlining, but that is no longer the case. 3115 3116@item 3117If an object file @code{O} depends on the proper body of a subunit through 3118inlining or instantiation, it depends on the parent unit of the subunit. 3119This means that any modification of the parent unit or one of its subunits 3120affects the compilation of @code{O}. 3121 3122@item 3123The object file for a parent unit depends on all its subunit body files. 3124 3125@item 3126The previous two rules meant that for purposes of computing dependencies and 3127recompilation, a body and all its subunits are treated as an indivisible whole. 3128 3129These rules are applied transitively: if unit @code{A} @emph{with}s 3130unit @code{B}, whose elaboration calls an inlined procedure in package 3131@code{C}, the object file for unit @code{A} will depend on the body of 3132@code{C}, in file @code{c.adb}. 3133 3134The set of dependent files described by these rules includes all the 3135files on which the unit is semantically dependent, as dictated by the 3136Ada language standard. However, it is a superset of what the 3137standard describes, because it includes generic, inline, and subunit 3138dependencies. 3139 3140An object file must be recreated by recompiling the corresponding source 3141file if any of the source files on which it depends are modified. For 3142example, if the @code{make} utility is used to control compilation, 3143the rule for an Ada object file must mention all the source files on 3144which the object file depends, according to the above definition. 3145The determination of the necessary 3146recompilations is done automatically when one uses @code{gnatmake}. 3147@end itemize 3148 3149@node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model 3150@anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{66}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{28} 3151@section The Ada Library Information Files 3152 3153 3154@geindex Ada Library Information files 3155 3156@geindex ALI files 3157 3158Each compilation actually generates two output files. The first of these 3159is the normal object file that has a @code{.o} extension. The second is a 3160text file containing full dependency information. It has the same 3161name as the source file, but an @code{.ali} extension. 3162This file is known as the Ada Library Information (@code{ALI}) file. 3163The following information is contained in the @code{ALI} file. 3164 3165 3166@itemize * 3167 3168@item 3169Version information (indicates which version of GNAT was used to compile 3170the unit(s) in question) 3171 3172@item 3173Main program information (including priority and time slice settings, 3174as well as the wide character encoding used during compilation). 3175 3176@item 3177List of arguments used in the @code{gcc} command for the compilation 3178 3179@item 3180Attributes of the unit, including configuration pragmas used, an indication 3181of whether the compilation was successful, exception model used etc. 3182 3183@item 3184A list of relevant restrictions applying to the unit (used for consistency) 3185checking. 3186 3187@item 3188Categorization information (e.g., use of pragma @code{Pure}). 3189 3190@item 3191Information on all @emph{with}ed units, including presence of 3192@code{Elaborate} or @code{Elaborate_All} pragmas. 3193 3194@item 3195Information from any @code{Linker_Options} pragmas used in the unit 3196 3197@item 3198Information on the use of @code{Body_Version} or @code{Version} 3199attributes in the unit. 3200 3201@item 3202Dependency information. This is a list of files, together with 3203time stamp and checksum information. These are files on which 3204the unit depends in the sense that recompilation is required 3205if any of these units are modified. 3206 3207@item 3208Cross-reference data. Contains information on all entities referenced 3209in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to 3210provide cross-reference information. 3211@end itemize 3212 3213For a full detailed description of the format of the @code{ALI} file, 3214see the source of the body of unit @code{Lib.Writ}, contained in file 3215@code{lib-writ.adb} in the GNAT compiler sources. 3216 3217@node Binding an Ada Program,GNAT and Libraries,The Ada Library Information Files,The GNAT Compilation Model 3218@anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{67}@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{29} 3219@section Binding an Ada Program 3220 3221 3222When using languages such as C and C++, once the source files have been 3223compiled the only remaining step in building an executable program 3224is linking the object modules together. This means that it is possible to 3225link an inconsistent version of a program, in which two units have 3226included different versions of the same header. 3227 3228The rules of Ada do not permit such an inconsistent program to be built. 3229For example, if two clients have different versions of the same package, 3230it is illegal to build a program containing these two clients. 3231These rules are enforced by the GNAT binder, which also determines an 3232elaboration order consistent with the Ada rules. 3233 3234The GNAT binder is run after all the object files for a program have 3235been created. It is given the name of the main program unit, and from 3236this it determines the set of units required by the program, by reading the 3237corresponding ALI files. It generates error messages if the program is 3238inconsistent or if no valid order of elaboration exists. 3239 3240If no errors are detected, the binder produces a main program, in Ada by 3241default, that contains calls to the elaboration procedures of those 3242compilation unit that require them, followed by 3243a call to the main program. This Ada program is compiled to generate the 3244object file for the main program. The name of 3245the Ada file is @code{b~xxx}.adb` (with the corresponding spec 3246@code{b~xxx}.ads`) where @code{xxx} is the name of the 3247main program unit. 3248 3249Finally, the linker is used to build the resulting executable program, 3250using the object from the main program from the bind step as well as the 3251object files for the Ada units of the program. 3252 3253@node GNAT and Libraries,Conditional Compilation,Binding an Ada Program,The GNAT Compilation Model 3254@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{2a}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{68} 3255@section GNAT and Libraries 3256 3257 3258@geindex Library building and using 3259 3260This section describes how to build and use libraries with GNAT, and also shows 3261how to recompile the GNAT run-time library. You should be familiar with the 3262Project Manager facility (see the @emph{GNAT_Project_Manager} chapter of the 3263@emph{GPRbuild User's Guide}) before reading this chapter. 3264 3265@menu 3266* Introduction to Libraries in GNAT:: 3267* General Ada Libraries:: 3268* Stand-alone Ada Libraries:: 3269* Rebuilding the GNAT Run-Time Library:: 3270 3271@end menu 3272 3273@node Introduction to Libraries in GNAT,General Ada Libraries,,GNAT and Libraries 3274@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{69}@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{6a} 3275@subsection Introduction to Libraries in GNAT 3276 3277 3278A library is, conceptually, a collection of objects which does not have its 3279own main thread of execution, but rather provides certain services to the 3280applications that use it. A library can be either statically linked with the 3281application, in which case its code is directly included in the application, 3282or, on platforms that support it, be dynamically linked, in which case 3283its code is shared by all applications making use of this library. 3284 3285GNAT supports both types of libraries. 3286In the static case, the compiled code can be provided in different ways. The 3287simplest approach is to provide directly the set of objects resulting from 3288compilation of the library source files. Alternatively, you can group the 3289objects into an archive using whatever commands are provided by the operating 3290system. For the latter case, the objects are grouped into a shared library. 3291 3292In the GNAT environment, a library has three types of components: 3293 3294 3295@itemize * 3296 3297@item 3298Source files, 3299 3300@item 3301@code{ALI} files (see @ref{28,,The Ada Library Information Files}), and 3302 3303@item 3304Object files, an archive or a shared library. 3305@end itemize 3306 3307A GNAT library may expose all its source files, which is useful for 3308documentation purposes. Alternatively, it may expose only the units needed by 3309an external user to make use of the library. That is to say, the specs 3310reflecting the library services along with all the units needed to compile 3311those specs, which can include generic bodies or any body implementing an 3312inlined routine. In the case of @emph{stand-alone libraries} those exposed 3313units are called @emph{interface units} (@ref{6b,,Stand-alone Ada Libraries}). 3314 3315All compilation units comprising an application, including those in a library, 3316need to be elaborated in an order partially defined by Ada's semantics. GNAT 3317computes the elaboration order from the @code{ALI} files and this is why they 3318constitute a mandatory part of GNAT libraries. 3319@emph{Stand-alone libraries} are the exception to this rule because a specific 3320library elaboration routine is produced independently of the application(s) 3321using the library. 3322 3323@node General Ada Libraries,Stand-alone Ada Libraries,Introduction to Libraries in GNAT,GNAT and Libraries 3324@anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{6d} 3325@subsection General Ada Libraries 3326 3327 3328@menu 3329* Building a library:: 3330* Installing a library:: 3331* Using a library:: 3332 3333@end menu 3334 3335@node Building a library,Installing a library,,General Ada Libraries 3336@anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{6e}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{6f} 3337@subsubsection Building a library 3338 3339 3340The easiest way to build a library is to use the Project Manager, 3341which supports a special type of project called a @emph{Library Project} 3342(see the @emph{Library Projects} section in the @emph{GNAT Project Manager} 3343chapter of the @emph{GPRbuild User's Guide}). 3344 3345A project is considered a library project, when two project-level attributes 3346are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to 3347control different aspects of library configuration, additional optional 3348project-level attributes can be specified: 3349 3350 3351@itemize * 3352 3353@item 3354 3355@table @asis 3356 3357@item @code{Library_Kind} 3358 3359This attribute controls whether the library is to be static or dynamic 3360@end table 3361 3362@item 3363 3364@table @asis 3365 3366@item @code{Library_Version} 3367 3368This attribute specifies the library version; this value is used 3369during dynamic linking of shared libraries to determine if the currently 3370installed versions of the binaries are compatible. 3371@end table 3372 3373@item 3374@code{Library_Options} 3375 3376@item 3377 3378@table @asis 3379 3380@item @code{Library_GCC} 3381 3382These attributes specify additional low-level options to be used during 3383library generation, and redefine the actual application used to generate 3384library. 3385@end table 3386@end itemize 3387 3388The GNAT Project Manager takes full care of the library maintenance task, 3389including recompilation of the source files for which objects do not exist 3390or are not up to date, assembly of the library archive, and installation of 3391the library (i.e., copying associated source, object and @code{ALI} files 3392to the specified location). 3393 3394Here is a simple library project file: 3395 3396@example 3397project My_Lib is 3398 for Source_Dirs use ("src1", "src2"); 3399 for Object_Dir use "obj"; 3400 for Library_Name use "mylib"; 3401 for Library_Dir use "lib"; 3402 for Library_Kind use "dynamic"; 3403end My_lib; 3404@end example 3405 3406and the compilation command to build and install the library: 3407 3408@example 3409$ gnatmake -Pmy_lib 3410@end example 3411 3412It is not entirely trivial to perform manually all the steps required to 3413produce a library. We recommend that you use the GNAT Project Manager 3414for this task. In special cases where this is not desired, the necessary 3415steps are discussed below. 3416 3417There are various possibilities for compiling the units that make up the 3418library: for example with a Makefile (@ref{70,,Using the GNU make Utility}) or 3419with a conventional script. For simple libraries, it is also possible to create 3420a dummy main program which depends upon all the packages that comprise the 3421interface of the library. This dummy main program can then be given to 3422@code{gnatmake}, which will ensure that all necessary objects are built. 3423 3424After this task is accomplished, you should follow the standard procedure 3425of the underlying operating system to produce the static or shared library. 3426 3427Here is an example of such a dummy program: 3428 3429@example 3430with My_Lib.Service1; 3431with My_Lib.Service2; 3432with My_Lib.Service3; 3433procedure My_Lib_Dummy is 3434begin 3435 null; 3436end; 3437@end example 3438 3439Here are the generic commands that will build an archive or a shared library. 3440 3441@example 3442# compiling the library 3443$ gnatmake -c my_lib_dummy.adb 3444 3445# we don't need the dummy object itself 3446$ rm my_lib_dummy.o my_lib_dummy.ali 3447 3448# create an archive with the remaining objects 3449$ ar rc libmy_lib.a *.o 3450# some systems may require "ranlib" to be run as well 3451 3452# or create a shared library 3453$ gcc -shared -o libmy_lib.so *.o 3454# some systems may require the code to have been compiled with -fPIC 3455 3456# remove the object files that are now in the library 3457$ rm *.o 3458 3459# Make the ALI files read-only so that gnatmake will not try to 3460# regenerate the objects that are in the library 3461$ chmod -w *.ali 3462@end example 3463 3464Please note that the library must have a name of the form @code{lib@emph{xxx}.a} 3465or @code{lib@emph{xxx}.so} (or @code{lib@emph{xxx}.dll} on Windows) in order to 3466be accessed by the directive @code{-l@emph{xxx}} at link time. 3467 3468@node Installing a library,Using a library,Building a library,General Ada Libraries 3469@anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{72} 3470@subsubsection Installing a library 3471 3472 3473@geindex ADA_PROJECT_PATH 3474 3475@geindex GPR_PROJECT_PATH 3476 3477If you use project files, library installation is part of the library build 3478process (see the @emph{Installing a Library with Project Files} section of the 3479@emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}). 3480 3481When project files are not an option, it is also possible, but not recommended, 3482to install the library so that the sources needed to use the library are on the 3483Ada source path and the ALI files & libraries be on the Ada Object path (see 3484@ref{73,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system 3485administrator can place general-purpose libraries in the default compiler 3486paths, by specifying the libraries' location in the configuration files 3487@code{ada_source_path} and @code{ada_object_path}. These configuration files 3488must be located in the GNAT installation tree at the same place as the gcc spec 3489file. The location of the gcc spec file can be determined as follows: 3490 3491@example 3492$ gcc -v 3493@end example 3494 3495The configuration files mentioned above have a simple format: each line 3496must contain one unique directory name. 3497Those names are added to the corresponding path 3498in their order of appearance in the file. The names can be either absolute 3499or relative; in the latter case, they are relative to where theses files 3500are located. 3501 3502The files @code{ada_source_path} and @code{ada_object_path} might not be 3503present in a 3504GNAT installation, in which case, GNAT will look for its run-time library in 3505the directories @code{adainclude} (for the sources) and @code{adalib} (for the 3506objects and @code{ALI} files). When the files exist, the compiler does not 3507look in @code{adainclude} and @code{adalib}, and thus the 3508@code{ada_source_path} file 3509must contain the location for the GNAT run-time sources (which can simply 3510be @code{adainclude}). In the same way, the @code{ada_object_path} file must 3511contain the location for the GNAT run-time objects (which can simply 3512be @code{adalib}). 3513 3514You can also specify a new default path to the run-time library at compilation 3515time with the switch @code{--RTS=rts-path}. You can thus choose / change 3516the run-time library you want your program to be compiled with. This switch is 3517recognized by @code{gcc}, @code{gnatmake}, @code{gnatbind}, 3518@code{gnatls}, @code{gnatfind} and @code{gnatxref}. 3519 3520It is possible to install a library before or after the standard GNAT 3521library, by reordering the lines in the configuration files. In general, a 3522library must be installed before the GNAT library if it redefines 3523any part of it. 3524 3525@node Using a library,,Installing a library,General Ada Libraries 3526@anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{74}@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{75} 3527@subsubsection Using a library 3528 3529 3530Once again, the project facility greatly simplifies the use of 3531libraries. In this context, using a library is just a matter of adding a 3532@emph{with} clause in the user project. For instance, to make use of the 3533library @code{My_Lib} shown in examples in earlier sections, you can 3534write: 3535 3536@example 3537with "my_lib"; 3538project My_Proj is 3539 ... 3540end My_Proj; 3541@end example 3542 3543Even if you have a third-party, non-Ada library, you can still use GNAT's 3544Project Manager facility to provide a wrapper for it. For example, the 3545following project, when @emph{with}ed by your main project, will link with the 3546third-party library @code{liba.a}: 3547 3548@example 3549project Liba is 3550 for Externally_Built use "true"; 3551 for Source_Files use (); 3552 for Library_Dir use "lib"; 3553 for Library_Name use "a"; 3554 for Library_Kind use "static"; 3555end Liba; 3556@end example 3557 3558This is an alternative to the use of @code{pragma Linker_Options}. It is 3559especially interesting in the context of systems with several interdependent 3560static libraries where finding a proper linker order is not easy and best be 3561left to the tools having visibility over project dependence information. 3562 3563In order to use an Ada library manually, you need to make sure that this 3564library is on both your source and object path 3565(see @ref{73,,Search Paths and the Run-Time Library (RTL)} 3566and @ref{76,,Search Paths for gnatbind}). Furthermore, when the objects are grouped 3567in an archive or a shared library, you need to specify the desired 3568library at link time. 3569 3570For example, you can use the library @code{mylib} installed in 3571@code{/dir/my_lib_src} and @code{/dir/my_lib_obj} with the following commands: 3572 3573@example 3574$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\ 3575 -largs -lmy_lib 3576@end example 3577 3578This can be expressed more simply: 3579 3580@example 3581$ gnatmake my_appl 3582@end example 3583 3584when the following conditions are met: 3585 3586 3587@itemize * 3588 3589@item 3590@code{/dir/my_lib_src} has been added by the user to the environment 3591variable 3592@geindex ADA_INCLUDE_PATH 3593@geindex environment variable; ADA_INCLUDE_PATH 3594@code{ADA_INCLUDE_PATH}, or by the administrator to the file 3595@code{ada_source_path} 3596 3597@item 3598@code{/dir/my_lib_obj} has been added by the user to the environment 3599variable 3600@geindex ADA_OBJECTS_PATH 3601@geindex environment variable; ADA_OBJECTS_PATH 3602@code{ADA_OBJECTS_PATH}, or by the administrator to the file 3603@code{ada_object_path} 3604 3605@item 3606a pragma @code{Linker_Options} has been added to one of the sources. 3607For example: 3608 3609@example 3610pragma Linker_Options ("-lmy_lib"); 3611@end example 3612@end itemize 3613 3614Note that you may also load a library dynamically at 3615run time given its filename, as illustrated in the GNAT @code{plugins} example 3616in the directory @code{share/examples/gnat/plugins} within the GNAT 3617install area. 3618 3619@node Stand-alone Ada Libraries,Rebuilding the GNAT Run-Time Library,General Ada Libraries,GNAT and Libraries 3620@anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{6b}@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{77} 3621@subsection Stand-alone Ada Libraries 3622 3623 3624@geindex Stand-alone libraries 3625 3626@menu 3627* Introduction to Stand-alone Libraries:: 3628* Building a Stand-alone Library:: 3629* Creating a Stand-alone Library to be used in a non-Ada context:: 3630* Restrictions in Stand-alone Libraries:: 3631 3632@end menu 3633 3634@node Introduction to Stand-alone Libraries,Building a Stand-alone Library,,Stand-alone Ada Libraries 3635@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{78}@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{79} 3636@subsubsection Introduction to Stand-alone Libraries 3637 3638 3639A Stand-alone Library (abbreviated 'SAL') is a library that contains the 3640necessary code to 3641elaborate the Ada units that are included in the library. In contrast with 3642an ordinary library, which consists of all sources, objects and @code{ALI} 3643files of the 3644library, a SAL may specify a restricted subset of compilation units 3645to serve as a library interface. In this case, the fully 3646self-sufficient set of files will normally consist of an objects 3647archive, the sources of interface units' specs, and the @code{ALI} 3648files of interface units. 3649If an interface spec contains a generic unit or an inlined subprogram, 3650the body's 3651source must also be provided; if the units that must be provided in the source 3652form depend on other units, the source and @code{ALI} files of those must 3653also be provided. 3654 3655The main purpose of a SAL is to minimize the recompilation overhead of client 3656applications when a new version of the library is installed. Specifically, 3657if the interface sources have not changed, client applications do not need to 3658be recompiled. If, furthermore, a SAL is provided in the shared form and its 3659version, controlled by @code{Library_Version} attribute, is not changed, 3660then the clients do not need to be relinked. 3661 3662SALs also allow the library providers to minimize the amount of library source 3663text exposed to the clients. Such 'information hiding' might be useful or 3664necessary for various reasons. 3665 3666Stand-alone libraries are also well suited to be used in an executable whose 3667main routine is not written in Ada. 3668 3669@node Building a Stand-alone Library,Creating a Stand-alone Library to be used in a non-Ada context,Introduction to Stand-alone Libraries,Stand-alone Ada Libraries 3670@anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{7b} 3671@subsubsection Building a Stand-alone Library 3672 3673 3674GNAT's Project facility provides a simple way of building and installing 3675stand-alone libraries; see the @emph{Stand-alone Library Projects} section 3676in the @emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}. 3677To be a Stand-alone Library Project, in addition to the two attributes 3678that make a project a Library Project (@code{Library_Name} and 3679@code{Library_Dir}; see the @emph{Library Projects} section in the 3680@emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}), 3681the attribute @code{Library_Interface} must be defined. For example: 3682 3683@example 3684for Library_Dir use "lib_dir"; 3685for Library_Name use "dummy"; 3686for Library_Interface use ("int1", "int1.child"); 3687@end example 3688 3689Attribute @code{Library_Interface} has a non-empty string list value, 3690each string in the list designating a unit contained in an immediate source 3691of the project file. 3692 3693When a Stand-alone Library is built, first the binder is invoked to build 3694a package whose name depends on the library name 3695(@code{b~dummy.ads/b} in the example above). 3696This binder-generated package includes initialization and 3697finalization procedures whose 3698names depend on the library name (@code{dummyinit} and @code{dummyfinal} 3699in the example 3700above). The object corresponding to this package is included in the library. 3701 3702You must ensure timely (e.g., prior to any use of interfaces in the SAL) 3703calling of these procedures if a static SAL is built, or if a shared SAL 3704is built 3705with the project-level attribute @code{Library_Auto_Init} set to 3706@code{"false"}. 3707 3708For a Stand-Alone Library, only the @code{ALI} files of the Interface Units 3709(those that are listed in attribute @code{Library_Interface}) are copied to 3710the Library Directory. As a consequence, only the Interface Units may be 3711imported from Ada units outside of the library. If other units are imported, 3712the binding phase will fail. 3713 3714It is also possible to build an encapsulated library where not only 3715the code to elaborate and finalize the library is embedded but also 3716ensuring that the library is linked only against static 3717libraries. So an encapsulated library only depends on system 3718libraries, all other code, including the GNAT runtime, is embedded. To 3719build an encapsulated library the attribute 3720@code{Library_Standalone} must be set to @code{encapsulated}: 3721 3722@example 3723for Library_Dir use "lib_dir"; 3724for Library_Name use "dummy"; 3725for Library_Kind use "dynamic"; 3726for Library_Interface use ("int1", "int1.child"); 3727for Library_Standalone use "encapsulated"; 3728@end example 3729 3730The default value for this attribute is @code{standard} in which case 3731a stand-alone library is built. 3732 3733The attribute @code{Library_Src_Dir} may be specified for a 3734Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a 3735single string value. Its value must be the path (absolute or relative to the 3736project directory) of an existing directory. This directory cannot be the 3737object directory or one of the source directories, but it can be the same as 3738the library directory. The sources of the Interface 3739Units of the library that are needed by an Ada client of the library will be 3740copied to the designated directory, called the Interface Copy directory. 3741These sources include the specs of the Interface Units, but they may also 3742include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always} 3743are used, or when there is a generic unit in the spec. Before the sources 3744are copied to the Interface Copy directory, an attempt is made to delete all 3745files in the Interface Copy directory. 3746 3747Building stand-alone libraries by hand is somewhat tedious, but for those 3748occasions when it is necessary here are the steps that you need to perform: 3749 3750 3751@itemize * 3752 3753@item 3754Compile all library sources. 3755 3756@item 3757Invoke the binder with the switch @code{-n} (No Ada main program), 3758with all the @code{ALI} files of the interfaces, and 3759with the switch @code{-L} to give specific names to the @code{init} 3760and @code{final} procedures. For example: 3761 3762@example 3763$ gnatbind -n int1.ali int2.ali -Lsal1 3764@end example 3765 3766@item 3767Compile the binder generated file: 3768 3769@example 3770$ gcc -c b~int2.adb 3771@end example 3772 3773@item 3774Link the dynamic library with all the necessary object files, 3775indicating to the linker the names of the @code{init} (and possibly 3776@code{final}) procedures for automatic initialization (and finalization). 3777The built library should be placed in a directory different from 3778the object directory. 3779 3780@item 3781Copy the @code{ALI} files of the interface to the library directory, 3782add in this copy an indication that it is an interface to a SAL 3783(i.e., add a word @code{SL} on the line in the @code{ALI} file that starts 3784with letter 'P') and make the modified copy of the @code{ALI} file 3785read-only. 3786@end itemize 3787 3788Using SALs is not different from using other libraries 3789(see @ref{74,,Using a library}). 3790 3791@node Creating a Stand-alone Library to be used in a non-Ada context,Restrictions in Stand-alone Libraries,Building a Stand-alone Library,Stand-alone Ada Libraries 3792@anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{7d} 3793@subsubsection Creating a Stand-alone Library to be used in a non-Ada context 3794 3795 3796It is easy to adapt the SAL build procedure discussed above for use of a SAL in 3797a non-Ada context. 3798 3799The only extra step required is to ensure that library interface subprograms 3800are compatible with the main program, by means of @code{pragma Export} 3801or @code{pragma Convention}. 3802 3803Here is an example of simple library interface for use with C main program: 3804 3805@example 3806package My_Package is 3807 3808 procedure Do_Something; 3809 pragma Export (C, Do_Something, "do_something"); 3810 3811 procedure Do_Something_Else; 3812 pragma Export (C, Do_Something_Else, "do_something_else"); 3813 3814end My_Package; 3815@end example 3816 3817On the foreign language side, you must provide a 'foreign' view of the 3818library interface; remember that it should contain elaboration routines in 3819addition to interface subprograms. 3820 3821The example below shows the content of @code{mylib_interface.h} (note 3822that there is no rule for the naming of this file, any name can be used) 3823 3824@example 3825/* the library elaboration procedure */ 3826extern void mylibinit (void); 3827 3828/* the library finalization procedure */ 3829extern void mylibfinal (void); 3830 3831/* the interface exported by the library */ 3832extern void do_something (void); 3833extern void do_something_else (void); 3834@end example 3835 3836Libraries built as explained above can be used from any program, provided 3837that the elaboration procedures (named @code{mylibinit} in the previous 3838example) are called before the library services are used. Any number of 3839libraries can be used simultaneously, as long as the elaboration 3840procedure of each library is called. 3841 3842Below is an example of a C program that uses the @code{mylib} library. 3843 3844@example 3845#include "mylib_interface.h" 3846 3847int 3848main (void) 3849@{ 3850 /* First, elaborate the library before using it */ 3851 mylibinit (); 3852 3853 /* Main program, using the library exported entities */ 3854 do_something (); 3855 do_something_else (); 3856 3857 /* Library finalization at the end of the program */ 3858 mylibfinal (); 3859 return 0; 3860@} 3861@end example 3862 3863Note that invoking any library finalization procedure generated by 3864@code{gnatbind} shuts down the Ada run-time environment. 3865Consequently, the 3866finalization of all Ada libraries must be performed at the end of the program. 3867No call to these libraries or to the Ada run-time library should be made 3868after the finalization phase. 3869 3870Note also that special care must be taken with multi-tasks 3871applications. The initialization and finalization routines are not 3872protected against concurrent access. If such requirement is needed it 3873must be ensured at the application level using a specific operating 3874system services like a mutex or a critical-section. 3875 3876@node Restrictions in Stand-alone Libraries,,Creating a Stand-alone Library to be used in a non-Ada context,Stand-alone Ada Libraries 3877@anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{7e}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{7f} 3878@subsubsection Restrictions in Stand-alone Libraries 3879 3880 3881The pragmas listed below should be used with caution inside libraries, 3882as they can create incompatibilities with other Ada libraries: 3883 3884 3885@itemize * 3886 3887@item 3888pragma @code{Locking_Policy} 3889 3890@item 3891pragma @code{Partition_Elaboration_Policy} 3892 3893@item 3894pragma @code{Queuing_Policy} 3895 3896@item 3897pragma @code{Task_Dispatching_Policy} 3898 3899@item 3900pragma @code{Unreserve_All_Interrupts} 3901@end itemize 3902 3903When using a library that contains such pragmas, the user must make sure 3904that all libraries use the same pragmas with the same values. Otherwise, 3905@code{Program_Error} will 3906be raised during the elaboration of the conflicting 3907libraries. The usage of these pragmas and its consequences for the user 3908should therefore be well documented. 3909 3910Similarly, the traceback in the exception occurrence mechanism should be 3911enabled or disabled in a consistent manner across all libraries. 3912Otherwise, Program_Error will be raised during the elaboration of the 3913conflicting libraries. 3914 3915If the @code{Version} or @code{Body_Version} 3916attributes are used inside a library, then you need to 3917perform a @code{gnatbind} step that specifies all @code{ALI} files in all 3918libraries, so that version identifiers can be properly computed. 3919In practice these attributes are rarely used, so this is unlikely 3920to be a consideration. 3921 3922@node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries 3923@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{81} 3924@subsection Rebuilding the GNAT Run-Time Library 3925 3926 3927@geindex GNAT Run-Time Library 3928@geindex rebuilding 3929 3930@geindex Building the GNAT Run-Time Library 3931 3932@geindex Rebuilding the GNAT Run-Time Library 3933 3934@geindex Run-Time Library 3935@geindex rebuilding 3936 3937It may be useful to recompile the GNAT library in various debugging or 3938experimentation contexts. A project file called 3939@code{libada.gpr} is provided to that effect and can be found in 3940the directory containing the GNAT library. The location of this 3941directory depends on the way the GNAT environment has been installed and can 3942be determined by means of the command: 3943 3944@example 3945$ gnatls -v 3946@end example 3947 3948The last entry in the source search path usually contains the 3949gnat library (the @code{adainclude} directory). This project file contains its 3950own documentation and in particular the set of instructions needed to rebuild a 3951new library and to use it. 3952 3953Note that rebuilding the GNAT Run-Time is only recommended for temporary 3954experiments or debugging, and is not supported. 3955 3956@geindex Conditional compilation 3957 3958@node Conditional Compilation,Mixed Language Programming,GNAT and Libraries,The GNAT Compilation Model 3959@anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{82}@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{2b} 3960@section Conditional Compilation 3961 3962 3963This section presents some guidelines for modeling conditional compilation in Ada and describes the 3964gnatprep preprocessor utility. 3965 3966@geindex Conditional compilation 3967 3968@menu 3969* Modeling Conditional Compilation in Ada:: 3970* Preprocessing with gnatprep:: 3971* Integrated Preprocessing:: 3972 3973@end menu 3974 3975@node Modeling Conditional Compilation in Ada,Preprocessing with gnatprep,,Conditional Compilation 3976@anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{84} 3977@subsection Modeling Conditional Compilation in Ada 3978 3979 3980It is often necessary to arrange for a single source program 3981to serve multiple purposes, where it is compiled in different 3982ways to achieve these different goals. Some examples of the 3983need for this feature are 3984 3985 3986@itemize * 3987 3988@item 3989Adapting a program to a different hardware environment 3990 3991@item 3992Adapting a program to a different target architecture 3993 3994@item 3995Turning debugging features on and off 3996 3997@item 3998Arranging for a program to compile with different compilers 3999@end itemize 4000 4001In C, or C++, the typical approach would be to use the preprocessor 4002that is defined as part of the language. The Ada language does not 4003contain such a feature. This is not an oversight, but rather a very 4004deliberate design decision, based on the experience that overuse of 4005the preprocessing features in C and C++ can result in programs that 4006are extremely difficult to maintain. For example, if we have ten 4007switches that can be on or off, this means that there are a thousand 4008separate programs, any one of which might not even be syntactically 4009correct, and even if syntactically correct, the resulting program 4010might not work correctly. Testing all combinations can quickly become 4011impossible. 4012 4013Nevertheless, the need to tailor programs certainly exists, and in 4014this section we will discuss how this can 4015be achieved using Ada in general, and GNAT in particular. 4016 4017@menu 4018* Use of Boolean Constants:: 4019* Debugging - A Special Case:: 4020* Conditionalizing Declarations:: 4021* Use of Alternative Implementations:: 4022* Preprocessing:: 4023 4024@end menu 4025 4026@node Use of Boolean Constants,Debugging - A Special Case,,Modeling Conditional Compilation in Ada 4027@anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{86} 4028@subsubsection Use of Boolean Constants 4029 4030 4031In the case where the difference is simply which code 4032sequence is executed, the cleanest solution is to use Boolean 4033constants to control which code is executed. 4034 4035@example 4036FP_Initialize_Required : constant Boolean := True; 4037... 4038if FP_Initialize_Required then 4039... 4040end if; 4041@end example 4042 4043Not only will the code inside the @code{if} statement not be executed if 4044the constant Boolean is @code{False}, but it will also be completely 4045deleted from the program. 4046However, the code is only deleted after the @code{if} statement 4047has been checked for syntactic and semantic correctness. 4048(In contrast, with preprocessors the code is deleted before the 4049compiler ever gets to see it, so it is not checked until the switch 4050is turned on.) 4051 4052@geindex Preprocessors (contrasted with conditional compilation) 4053 4054Typically the Boolean constants will be in a separate package, 4055something like: 4056 4057@example 4058package Config is 4059 FP_Initialize_Required : constant Boolean := True; 4060 Reset_Available : constant Boolean := False; 4061 ... 4062end Config; 4063@end example 4064 4065The @code{Config} package exists in multiple forms for the various targets, 4066with an appropriate script selecting the version of @code{Config} needed. 4067Then any other unit requiring conditional compilation can do a @emph{with} 4068of @code{Config} to make the constants visible. 4069 4070@node Debugging - A Special Case,Conditionalizing Declarations,Use of Boolean Constants,Modeling Conditional Compilation in Ada 4071@anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{87}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{88} 4072@subsubsection Debugging - A Special Case 4073 4074 4075A common use of conditional code is to execute statements (for example 4076dynamic checks, or output of intermediate results) under control of a 4077debug switch, so that the debugging behavior can be turned on and off. 4078This can be done using a Boolean constant to control whether the code 4079is active: 4080 4081@example 4082if Debugging then 4083 Put_Line ("got to the first stage!"); 4084end if; 4085@end example 4086 4087or 4088 4089@example 4090if Debugging and then Temperature > 999.0 then 4091 raise Temperature_Crazy; 4092end if; 4093@end example 4094 4095@geindex pragma Assert 4096 4097Since this is a common case, there are special features to deal with 4098this in a convenient manner. For the case of tests, Ada 2005 has added 4099a pragma @code{Assert} that can be used for such tests. This pragma is modeled 4100on the @code{Assert} pragma that has always been available in GNAT, so this 4101feature may be used with GNAT even if you are not using Ada 2005 features. 4102The use of pragma @code{Assert} is described in the 4103@cite{GNAT_Reference_Manual}, but as an 4104example, the last test could be written: 4105 4106@example 4107pragma Assert (Temperature <= 999.0, "Temperature Crazy"); 4108@end example 4109 4110or simply 4111 4112@example 4113pragma Assert (Temperature <= 999.0); 4114@end example 4115 4116In both cases, if assertions are active and the temperature is excessive, 4117the exception @code{Assert_Failure} will be raised, with the given string in 4118the first case or a string indicating the location of the pragma in the second 4119case used as the exception message. 4120 4121@geindex pragma Assertion_Policy 4122 4123You can turn assertions on and off by using the @code{Assertion_Policy} 4124pragma. 4125 4126@geindex -gnata switch 4127 4128This is an Ada 2005 pragma which is implemented in all modes by 4129GNAT. Alternatively, you can use the @code{-gnata} switch 4130to enable assertions from the command line, which applies to 4131all versions of Ada. 4132 4133@geindex pragma Debug 4134 4135For the example above with the @code{Put_Line}, the GNAT-specific pragma 4136@code{Debug} can be used: 4137 4138@example 4139pragma Debug (Put_Line ("got to the first stage!")); 4140@end example 4141 4142If debug pragmas are enabled, the argument, which must be of the form of 4143a procedure call, is executed (in this case, @code{Put_Line} will be called). 4144Only one call can be present, but of course a special debugging procedure 4145containing any code you like can be included in the program and then 4146called in a pragma @code{Debug} argument as needed. 4147 4148One advantage of pragma @code{Debug} over the @code{if Debugging then} 4149construct is that pragma @code{Debug} can appear in declarative contexts, 4150such as at the very beginning of a procedure, before local declarations have 4151been elaborated. 4152 4153@geindex pragma Debug_Policy 4154 4155Debug pragmas are enabled using either the @code{-gnata} switch that also 4156controls assertions, or with a separate Debug_Policy pragma. 4157 4158The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used 4159in Ada 95 and Ada 83 programs as well), and is analogous to 4160pragma @code{Assertion_Policy} to control assertions. 4161 4162@code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas, 4163and thus they can appear in @code{gnat.adc} if you are not using a 4164project file, or in the file designated to contain configuration pragmas 4165in a project file. 4166They then apply to all subsequent compilations. In practice the use of 4167the @code{-gnata} switch is often the most convenient method of controlling 4168the status of these pragmas. 4169 4170Note that a pragma is not a statement, so in contexts where a statement 4171sequence is required, you can't just write a pragma on its own. You have 4172to add a @code{null} statement. 4173 4174@example 4175if ... then 4176 ... -- some statements 4177else 4178 pragma Assert (Num_Cases < 10); 4179 null; 4180end if; 4181@end example 4182 4183@node Conditionalizing Declarations,Use of Alternative Implementations,Debugging - A Special Case,Modeling Conditional Compilation in Ada 4184@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{89}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{8a} 4185@subsubsection Conditionalizing Declarations 4186 4187 4188In some cases it may be necessary to conditionalize declarations to meet 4189different requirements. For example we might want a bit string whose length 4190is set to meet some hardware message requirement. 4191 4192This may be possible using declare blocks controlled 4193by conditional constants: 4194 4195@example 4196if Small_Machine then 4197 declare 4198 X : Bit_String (1 .. 10); 4199 begin 4200 ... 4201 end; 4202else 4203 declare 4204 X : Large_Bit_String (1 .. 1000); 4205 begin 4206 ... 4207 end; 4208end if; 4209@end example 4210 4211Note that in this approach, both declarations are analyzed by the 4212compiler so this can only be used where both declarations are legal, 4213even though one of them will not be used. 4214 4215Another approach is to define integer constants, e.g., @code{Bits_Per_Word}, 4216or Boolean constants, e.g., @code{Little_Endian}, and then write declarations 4217that are parameterized by these constants. For example 4218 4219@example 4220for Rec use 4221 Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word; 4222end record; 4223@end example 4224 4225If @code{Bits_Per_Word} is set to 32, this generates either 4226 4227@example 4228for Rec use 4229 Field1 at 0 range 0 .. 32; 4230end record; 4231@end example 4232 4233for the big endian case, or 4234 4235@example 4236for Rec use record 4237 Field1 at 0 range 10 .. 32; 4238end record; 4239@end example 4240 4241for the little endian case. Since a powerful subset of Ada expression 4242notation is usable for creating static constants, clever use of this 4243feature can often solve quite difficult problems in conditionalizing 4244compilation (note incidentally that in Ada 95, the little endian 4245constant was introduced as @code{System.Default_Bit_Order}, so you do not 4246need to define this one yourself). 4247 4248@node Use of Alternative Implementations,Preprocessing,Conditionalizing Declarations,Modeling Conditional Compilation in Ada 4249@anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{8b}@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{8c} 4250@subsubsection Use of Alternative Implementations 4251 4252 4253In some cases, none of the approaches described above are adequate. This 4254can occur for example if the set of declarations required is radically 4255different for two different configurations. 4256 4257In this situation, the official Ada way of dealing with conditionalizing 4258such code is to write separate units for the different cases. As long as 4259this does not result in excessive duplication of code, this can be done 4260without creating maintenance problems. The approach is to share common 4261code as far as possible, and then isolate the code and declarations 4262that are different. Subunits are often a convenient method for breaking 4263out a piece of a unit that is to be conditionalized, with separate files 4264for different versions of the subunit for different targets, where the 4265build script selects the right one to give to the compiler. 4266 4267@geindex Subunits (and conditional compilation) 4268 4269As an example, consider a situation where a new feature in Ada 2005 4270allows something to be done in a really nice way. But your code must be able 4271to compile with an Ada 95 compiler. Conceptually you want to say: 4272 4273@example 4274if Ada_2005 then 4275 ... neat Ada 2005 code 4276else 4277 ... not quite as neat Ada 95 code 4278end if; 4279@end example 4280 4281where @code{Ada_2005} is a Boolean constant. 4282 4283But this won't work when @code{Ada_2005} is set to @code{False}, 4284since the @code{then} clause will be illegal for an Ada 95 compiler. 4285(Recall that although such unreachable code would eventually be deleted 4286by the compiler, it still needs to be legal. If it uses features 4287introduced in Ada 2005, it will be illegal in Ada 95.) 4288 4289So instead we write 4290 4291@example 4292procedure Insert is separate; 4293@end example 4294 4295Then we have two files for the subunit @code{Insert}, with the two sets of 4296code. 4297If the package containing this is called @code{File_Queries}, then we might 4298have two files 4299 4300 4301@itemize * 4302 4303@item 4304@code{file_queries-insert-2005.adb} 4305 4306@item 4307@code{file_queries-insert-95.adb} 4308@end itemize 4309 4310and the build script renames the appropriate file to @code{file_queries-insert.adb} and then carries out the compilation. 4311 4312This can also be done with project files' naming schemes. For example: 4313 4314@example 4315for body ("File_Queries.Insert") use "file_queries-insert-2005.ada"; 4316@end example 4317 4318Note also that with project files it is desirable to use a different extension 4319than @code{ads} / @code{adb} for alternative versions. Otherwise a naming 4320conflict may arise through another commonly used feature: to declare as part 4321of the project a set of directories containing all the sources obeying the 4322default naming scheme. 4323 4324The use of alternative units is certainly feasible in all situations, 4325and for example the Ada part of the GNAT run-time is conditionalized 4326based on the target architecture using this approach. As a specific example, 4327consider the implementation of the AST feature in VMS. There is one 4328spec: @code{s-asthan.ads} which is the same for all architectures, and three 4329bodies: 4330 4331 4332@itemize * 4333 4334@item 4335 4336@table @asis 4337 4338@item @code{s-asthan.adb} 4339 4340used for all non-VMS operating systems 4341@end table 4342 4343@item 4344 4345@table @asis 4346 4347@item @code{s-asthan-vms-alpha.adb} 4348 4349used for VMS on the Alpha 4350@end table 4351 4352@item 4353 4354@table @asis 4355 4356@item @code{s-asthan-vms-ia64.adb} 4357 4358used for VMS on the ia64 4359@end table 4360@end itemize 4361 4362The dummy version @code{s-asthan.adb} simply raises exceptions noting that 4363this operating system feature is not available, and the two remaining 4364versions interface with the corresponding versions of VMS to provide 4365VMS-compatible AST handling. The GNAT build script knows the architecture 4366and operating system, and automatically selects the right version, 4367renaming it if necessary to @code{s-asthan.adb} before the run-time build. 4368 4369Another style for arranging alternative implementations is through Ada's 4370access-to-subprogram facility. 4371In case some functionality is to be conditionally included, 4372you can declare an access-to-procedure variable @code{Ref} that is initialized 4373to designate a 'do nothing' procedure, and then invoke @code{Ref.all} 4374when appropriate. 4375In some library package, set @code{Ref} to @code{Proc'Access} for some 4376procedure @code{Proc} that performs the relevant processing. 4377The initialization only occurs if the library package is included in the 4378program. 4379The same idea can also be implemented using tagged types and dispatching 4380calls. 4381 4382@node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada 4383@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{8d}@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{8e} 4384@subsubsection Preprocessing 4385 4386 4387@geindex Preprocessing 4388 4389Although it is quite possible to conditionalize code without the use of 4390C-style preprocessing, as described earlier in this section, it is 4391nevertheless convenient in some cases to use the C approach. Moreover, 4392older Ada compilers have often provided some preprocessing capability, 4393so legacy code may depend on this approach, even though it is not 4394standard. 4395 4396To accommodate such use, GNAT provides a preprocessor (modeled to a large 4397extent on the various preprocessors that have been used 4398with legacy code on other compilers, to enable easier transition). 4399 4400@geindex gnatprep 4401 4402The preprocessor may be used in two separate modes. It can be used quite 4403separately from the compiler, to generate a separate output source file 4404that is then fed to the compiler as a separate step. This is the 4405@code{gnatprep} utility, whose use is fully described in 4406@ref{8f,,Preprocessing with gnatprep}. 4407 4408The preprocessing language allows such constructs as 4409 4410@example 4411#if DEBUG or else (PRIORITY > 4) then 4412 sequence of declarations 4413#else 4414 completely different sequence of declarations 4415#end if; 4416@end example 4417 4418The values of the symbols @code{DEBUG} and @code{PRIORITY} can be 4419defined either on the command line or in a separate file. 4420 4421The other way of running the preprocessor is even closer to the C style and 4422often more convenient. In this approach the preprocessing is integrated into 4423the compilation process. The compiler is given the preprocessor input which 4424includes @code{#if} lines etc, and then the compiler carries out the 4425preprocessing internally and processes the resulting output. 4426For more details on this approach, see @ref{90,,Integrated Preprocessing}. 4427 4428@node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation 4429@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{91}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{8f} 4430@subsection Preprocessing with @code{gnatprep} 4431 4432 4433@geindex gnatprep 4434 4435@geindex Preprocessing (gnatprep) 4436 4437This section discusses how to use GNAT's @code{gnatprep} utility for simple 4438preprocessing. 4439Although designed for use with GNAT, @code{gnatprep} does not depend on any 4440special GNAT features. 4441For further discussion of conditional compilation in general, see 4442@ref{2b,,Conditional Compilation}. 4443 4444@menu 4445* Preprocessing Symbols:: 4446* Using gnatprep:: 4447* Switches for gnatprep:: 4448* Form of Definitions File:: 4449* Form of Input Text for gnatprep:: 4450 4451@end menu 4452 4453@node Preprocessing Symbols,Using gnatprep,,Preprocessing with gnatprep 4454@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{93} 4455@subsubsection Preprocessing Symbols 4456 4457 4458Preprocessing symbols are defined in @emph{definition files} and referenced in the 4459sources to be preprocessed. A preprocessing symbol is an identifier, following 4460normal Ada (case-insensitive) rules for its syntax, with the restriction that 4461all characters need to be in the ASCII set (no accented letters). 4462 4463@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep 4464@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{94}@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{95} 4465@subsubsection Using @code{gnatprep} 4466 4467 4468To call @code{gnatprep} use: 4469 4470@example 4471$ gnatprep [ switches ] infile outfile [ deffile ] 4472@end example 4473 4474where 4475 4476 4477@itemize * 4478 4479@item 4480 4481@table @asis 4482 4483@item @emph{switches} 4484 4485is an optional sequence of switches as described in the next section. 4486@end table 4487 4488@item 4489 4490@table @asis 4491 4492@item @emph{infile} 4493 4494is the full name of the input file, which is an Ada source 4495file containing preprocessor directives. 4496@end table 4497 4498@item 4499 4500@table @asis 4501 4502@item @emph{outfile} 4503 4504is the full name of the output file, which is an Ada source 4505in standard Ada form. When used with GNAT, this file name will 4506normally have an @code{ads} or @code{adb} suffix. 4507@end table 4508 4509@item 4510 4511@table @asis 4512 4513@item @code{deffile} 4514 4515is the full name of a text file containing definitions of 4516preprocessing symbols to be referenced by the preprocessor. This argument is 4517optional, and can be replaced by the use of the @code{-D} switch. 4518@end table 4519@end itemize 4520 4521@node Switches for gnatprep,Form of Definitions File,Using gnatprep,Preprocessing with gnatprep 4522@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{96}@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{97} 4523@subsubsection Switches for @code{gnatprep} 4524 4525 4526@geindex --version (gnatprep) 4527 4528 4529@table @asis 4530 4531@item @code{--version} 4532 4533Display Copyright and version, then exit disregarding all other options. 4534@end table 4535 4536@geindex --help (gnatprep) 4537 4538 4539@table @asis 4540 4541@item @code{--help} 4542 4543If @code{--version} was not used, display usage and then exit disregarding 4544all other options. 4545@end table 4546 4547@geindex -b (gnatprep) 4548 4549 4550@table @asis 4551 4552@item @code{-b} 4553 4554Causes both preprocessor lines and the lines deleted by 4555preprocessing to be replaced by blank lines in the output source file, 4556preserving line numbers in the output file. 4557@end table 4558 4559@geindex -c (gnatprep) 4560 4561 4562@table @asis 4563 4564@item @code{-c} 4565 4566Causes both preprocessor lines and the lines deleted 4567by preprocessing to be retained in the output source as comments marked 4568with the special string @code{"--! "}. This option will result in line numbers 4569being preserved in the output file. 4570@end table 4571 4572@geindex -C (gnatprep) 4573 4574 4575@table @asis 4576 4577@item @code{-C} 4578 4579Causes comments to be scanned. Normally comments are ignored by gnatprep. 4580If this option is specified, then comments are scanned and any $symbol 4581substitutions performed as in program text. This is particularly useful 4582when structured comments are used (e.g., for programs written in a 4583pre-2014 version of the SPARK Ada subset). Note that this switch is not 4584available when doing integrated preprocessing (it would be useless in 4585this context since comments are ignored by the compiler in any case). 4586@end table 4587 4588@geindex -D (gnatprep) 4589 4590 4591@table @asis 4592 4593@item @code{-D@emph{symbol}[=@emph{value}]} 4594 4595Defines a new preprocessing symbol with the specified value. If no value is given 4596on the command line, then symbol is considered to be @code{True}. This switch 4597can be used in place of a definition file. 4598@end table 4599 4600@geindex -r (gnatprep) 4601 4602 4603@table @asis 4604 4605@item @code{-r} 4606 4607Causes a @code{Source_Reference} pragma to be generated that 4608references the original input file, so that error messages will use 4609the file name of this original file. The use of this switch implies 4610that preprocessor lines are not to be removed from the file, so its 4611use will force @code{-b} mode if @code{-c} 4612has not been specified explicitly. 4613 4614Note that if the file to be preprocessed contains multiple units, then 4615it will be necessary to @code{gnatchop} the output file from 4616@code{gnatprep}. If a @code{Source_Reference} pragma is present 4617in the preprocessed file, it will be respected by 4618@code{gnatchop -r} 4619so that the final chopped files will correctly refer to the original 4620input source file for @code{gnatprep}. 4621@end table 4622 4623@geindex -s (gnatprep) 4624 4625 4626@table @asis 4627 4628@item @code{-s} 4629 4630Causes a sorted list of symbol names and values to be 4631listed on the standard output file. 4632@end table 4633 4634@geindex -T (gnatprep) 4635 4636 4637@table @asis 4638 4639@item @code{-T} 4640 4641Use LF as line terminators when writing files. By default the line terminator 4642of the host (LF under unix, CR/LF under Windows) is used. 4643@end table 4644 4645@geindex -u (gnatprep) 4646 4647 4648@table @asis 4649 4650@item @code{-u} 4651 4652Causes undefined symbols to be treated as having the value FALSE in the context 4653of a preprocessor test. In the absence of this option, an undefined symbol in 4654a @code{#if} or @code{#elsif} test will be treated as an error. 4655@end table 4656 4657@geindex -v (gnatprep) 4658 4659 4660@table @asis 4661 4662@item @code{-v} 4663 4664Verbose mode: generates more output about work done. 4665@end table 4666 4667Note: if neither @code{-b} nor @code{-c} is present, 4668then preprocessor lines and 4669deleted lines are completely removed from the output, unless -r is 4670specified, in which case -b is assumed. 4671 4672@node Form of Definitions File,Form of Input Text for gnatprep,Switches for gnatprep,Preprocessing with gnatprep 4673@anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{99} 4674@subsubsection Form of Definitions File 4675 4676 4677The definitions file contains lines of the form: 4678 4679@example 4680symbol := value 4681@end example 4682 4683where @code{symbol} is a preprocessing symbol, and @code{value} is one of the following: 4684 4685 4686@itemize * 4687 4688@item 4689Empty, corresponding to a null substitution, 4690 4691@item 4692A string literal using normal Ada syntax, or 4693 4694@item 4695Any sequence of characters from the set @{letters, digits, period, underline@}. 4696@end itemize 4697 4698Comment lines may also appear in the definitions file, starting with 4699the usual @code{--}, 4700and comments may be added to the definitions lines. 4701 4702@node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep 4703@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{9a}@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{9b} 4704@subsubsection Form of Input Text for @code{gnatprep} 4705 4706 4707The input text may contain preprocessor conditional inclusion lines, 4708as well as general symbol substitution sequences. 4709 4710The preprocessor conditional inclusion commands have the form: 4711 4712@example 4713#if <expression> [then] 4714 lines 4715#elsif <expression> [then] 4716 lines 4717#elsif <expression> [then] 4718 lines 4719... 4720#else 4721 lines 4722#end if; 4723@end example 4724 4725In this example, <expression> is defined by the following grammar: 4726 4727@example 4728<expression> ::= <symbol> 4729<expression> ::= <symbol> = "<value>" 4730<expression> ::= <symbol> = <symbol> 4731<expression> ::= <symbol> = <integer> 4732<expression> ::= <symbol> > <integer> 4733<expression> ::= <symbol> >= <integer> 4734<expression> ::= <symbol> < <integer> 4735<expression> ::= <symbol> <= <integer> 4736<expression> ::= <symbol> 'Defined 4737<expression> ::= not <expression> 4738<expression> ::= <expression> and <expression> 4739<expression> ::= <expression> or <expression> 4740<expression> ::= <expression> and then <expression> 4741<expression> ::= <expression> or else <expression> 4742<expression> ::= ( <expression> ) 4743@end example 4744 4745Note the following restriction: it is not allowed to have "and" or "or" 4746following "not" in the same expression without parentheses. For example, this 4747is not allowed: 4748 4749@example 4750not X or Y 4751@end example 4752 4753This can be expressed instead as one of the following forms: 4754 4755@example 4756(not X) or Y 4757not (X or Y) 4758@end example 4759 4760For the first test (<expression> ::= <symbol>) the symbol must have 4761either the value true or false, that is to say the right-hand of the 4762symbol definition must be one of the (case-insensitive) literals 4763@code{True} or @code{False}. If the value is true, then the 4764corresponding lines are included, and if the value is false, they are 4765excluded. 4766 4767When comparing a symbol to an integer, the integer is any non negative 4768literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or 47692#11#. The symbol value must also be a non negative integer. Integer values 4770in the range 0 .. 2**31-1 are supported. 4771 4772The test (<expression> ::= <symbol>'Defined) is true only if 4773the symbol has been defined in the definition file or by a @code{-D} 4774switch on the command line. Otherwise, the test is false. 4775 4776The equality tests are case insensitive, as are all the preprocessor lines. 4777 4778If the symbol referenced is not defined in the symbol definitions file, 4779then the effect depends on whether or not switch @code{-u} 4780is specified. If so, then the symbol is treated as if it had the value 4781false and the test fails. If this switch is not specified, then 4782it is an error to reference an undefined symbol. It is also an error to 4783reference a symbol that is defined with a value other than @code{True} 4784or @code{False}. 4785 4786The use of the @code{not} operator inverts the sense of this logical test. 4787The @code{not} operator cannot be combined with the @code{or} or @code{and} 4788operators, without parentheses. For example, "if not X or Y then" is not 4789allowed, but "if (not X) or Y then" and "if not (X or Y) then" are. 4790 4791The @code{then} keyword is optional as shown 4792 4793The @code{#} must be the first non-blank character on a line, but 4794otherwise the format is free form. Spaces or tabs may appear between 4795the @code{#} and the keyword. The keywords and the symbols are case 4796insensitive as in normal Ada code. Comments may be used on a 4797preprocessor line, but other than that, no other tokens may appear on a 4798preprocessor line. Any number of @code{elsif} clauses can be present, 4799including none at all. The @code{else} is optional, as in Ada. 4800 4801The @code{#} marking the start of a preprocessor line must be the first 4802non-blank character on the line, i.e., it must be preceded only by 4803spaces or horizontal tabs. 4804 4805Symbol substitution outside of preprocessor lines is obtained by using 4806the sequence: 4807 4808@example 4809$symbol 4810@end example 4811 4812anywhere within a source line, except in a comment or within a 4813string literal. The identifier 4814following the @code{$} must match one of the symbols defined in the symbol 4815definition file, and the result is to substitute the value of the 4816symbol in place of @code{$symbol} in the output file. 4817 4818Note that although the substitution of strings within a string literal 4819is not possible, it is possible to have a symbol whose defined value is 4820a string literal. So instead of setting XYZ to @code{hello} and writing: 4821 4822@example 4823Header : String := "$XYZ"; 4824@end example 4825 4826you should set XYZ to @code{"hello"} and write: 4827 4828@example 4829Header : String := $XYZ; 4830@end example 4831 4832and then the substitution will occur as desired. 4833 4834@node Integrated Preprocessing,,Preprocessing with gnatprep,Conditional Compilation 4835@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{90} 4836@subsection Integrated Preprocessing 4837 4838 4839As noted above, a file to be preprocessed consists of Ada source code 4840in which preprocessing lines have been inserted. However, 4841instead of using @code{gnatprep} to explicitly preprocess a file as a separate 4842step before compilation, you can carry out the preprocessing implicitly 4843as part of compilation. Such @emph{integrated preprocessing}, which is the common 4844style with C, is performed when either or both of the following switches 4845are passed to the compiler: 4846 4847@quotation 4848 4849 4850@itemize * 4851 4852@item 4853@code{-gnatep}, which specifies the @emph{preprocessor data file}. 4854This file dictates how the source files will be preprocessed (e.g., which 4855symbol definition files apply to which sources). 4856 4857@item 4858@code{-gnateD}, which defines values for preprocessing symbols. 4859@end itemize 4860@end quotation 4861 4862Integrated preprocessing applies only to Ada source files, it is 4863not available for configuration pragma files. 4864 4865With integrated preprocessing, the output from the preprocessor is not, 4866by default, written to any external file. Instead it is passed 4867internally to the compiler. To preserve the result of 4868preprocessing in a file, either run @code{gnatprep} 4869in standalone mode or else supply the @code{-gnateG} switch 4870(described below) to the compiler. 4871 4872When using project files: 4873 4874@quotation 4875 4876 4877@itemize * 4878 4879@item 4880the builder switch @code{-x} should be used if any Ada source is 4881compiled with @code{gnatep=}, so that the compiler finds the 4882@emph{preprocessor data file}. 4883 4884@item 4885the preprocessing data file and the symbol definition files should be 4886located in the source directories of the project. 4887@end itemize 4888@end quotation 4889 4890Note that the @code{gnatmake} switch @code{-m} will almost 4891always trigger recompilation for sources that are preprocessed, 4892because @code{gnatmake} cannot compute the checksum of the source after 4893preprocessing. 4894 4895The actual preprocessing function is described in detail in 4896@ref{8f,,Preprocessing with gnatprep}. This section explains the switches 4897that relate to integrated preprocessing. 4898 4899@geindex -gnatep (gcc) 4900 4901 4902@table @asis 4903 4904@item @code{-gnatep=@emph{preprocessor_data_file}} 4905 4906This switch specifies the file name (without directory 4907information) of the preprocessor data file. Either place this file 4908in one of the source directories, or, when using project 4909files, reference the project file's directory via the 4910@code{project_name'Project_Dir} project attribute; e.g: 4911 4912@quotation 4913 4914@example 4915project Prj is 4916 package Compiler is 4917 for Switches ("Ada") use 4918 ("-gnatep=" & Prj'Project_Dir & "prep.def"); 4919 end Compiler; 4920end Prj; 4921@end example 4922@end quotation 4923 4924A preprocessor data file is a text file that contains @emph{preprocessor 4925control lines}. A preprocessor control line directs the preprocessing of 4926either a particular source file, or, analogous to @code{others} in Ada, 4927all sources not specified elsewhere in the preprocessor data file. 4928A preprocessor control line 4929can optionally identify a @emph{definition file} that assigns values to 4930preprocessor symbols, as well as a list of switches that relate to 4931preprocessing. 4932Empty lines and comments (using Ada syntax) are also permitted, with no 4933semantic effect. 4934 4935Here's an example of a preprocessor data file: 4936 4937@quotation 4938 4939@example 4940"toto.adb" "prep.def" -u 4941-- Preprocess toto.adb, using definition file prep.def 4942-- Undefined symbols are treated as False 4943 4944* -c -DVERSION=V101 4945-- Preprocess all other sources without using a definition file 4946-- Suppressed lined are commented 4947-- Symbol VERSION has the value V101 4948 4949"tata.adb" "prep2.def" -s 4950-- Preprocess tata.adb, using definition file prep2.def 4951-- List all symbols with their values 4952@end example 4953@end quotation 4954 4955A preprocessor control line has the following syntax: 4956 4957@quotation 4958 4959@example 4960<preprocessor_control_line> ::= 4961 <preprocessor_input> [ <definition_file_name> ] @{ <switch> @} 4962 4963<preprocessor_input> ::= <source_file_name> | '*' 4964 4965<definition_file_name> ::= <string_literal> 4966 4967<source_file_name> := <string_literal> 4968 4969<switch> := (See below for list) 4970@end example 4971@end quotation 4972 4973Thus each preprocessor control line starts with either a literal string or 4974the character '*': 4975 4976 4977@itemize * 4978 4979@item 4980A literal string is the file name (without directory information) of the source 4981file that will be input to the preprocessor. 4982 4983@item 4984The character '*' is a wild-card indicator; the additional parameters on the line 4985indicate the preprocessing for all the sources 4986that are not specified explicitly on other lines (the order of the lines is not 4987significant). 4988@end itemize 4989 4990It is an error to have two lines with the same file name or two 4991lines starting with the character '*'. 4992 4993After the file name or '*', an optional literal string specifies the name of 4994the definition file to be used for preprocessing 4995(@ref{98,,Form of Definitions File}). The definition files are found by the 4996compiler in one of the source directories. In some cases, when compiling 4997a source in a directory other than the current directory, if the definition 4998file is in the current directory, it may be necessary to add the current 4999directory as a source directory through the @code{-I} switch; otherwise 5000the compiler would not find the definition file. 5001 5002Finally, switches similar to those of @code{gnatprep} may optionally appear: 5003 5004 5005@table @asis 5006 5007@item @code{-b} 5008 5009Causes both preprocessor lines and the lines deleted by 5010preprocessing to be replaced by blank lines, preserving the line number. 5011This switch is always implied; however, if specified after @code{-c} 5012it cancels the effect of @code{-c}. 5013 5014@item @code{-c} 5015 5016Causes both preprocessor lines and the lines deleted 5017by preprocessing to be retained as comments marked 5018with the special string '@cite{--!}'. 5019 5020@item @code{-D@emph{symbol}=@emph{new_value}} 5021 5022Define or redefine @code{symbol} to have @code{new_value} as its value. 5023The permitted form for @code{symbol} is either an Ada identifier, or any Ada reserved word 5024aside from @code{if}, 5025@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. 5026The permitted form for @code{new_value} is a literal string, an Ada identifier or any Ada reserved 5027word. A symbol declared with this switch replaces a symbol with the 5028same name defined in a definition file. 5029 5030@item @code{-s} 5031 5032Causes a sorted list of symbol names and values to be 5033listed on the standard output file. 5034 5035@item @code{-u} 5036 5037Causes undefined symbols to be treated as having the value @code{FALSE} 5038in the context 5039of a preprocessor test. In the absence of this option, an undefined symbol in 5040a @code{#if} or @code{#elsif} test will be treated as an error. 5041@end table 5042@end table 5043 5044@geindex -gnateD (gcc) 5045 5046 5047@table @asis 5048 5049@item @code{-gnateD@emph{symbol}[=@emph{new_value}]} 5050 5051Define or redefine @code{symbol} to have @code{new_value} as its value. If no value 5052is supplied, then the value of @code{symbol} is @code{True}. 5053The form of @code{symbol} is an identifier, following normal Ada (case-insensitive) 5054rules for its syntax, and @code{new_value} is either an arbitrary string between double 5055quotes or any sequence (including an empty sequence) of characters from the 5056set (letters, digits, period, underline). 5057Ada reserved words may be used as symbols, with the exceptions of @code{if}, 5058@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. 5059 5060Examples: 5061 5062@quotation 5063 5064@example 5065-gnateDToto=Tata 5066-gnateDFoo 5067-gnateDFoo=\"Foo-Bar\" 5068@end example 5069@end quotation 5070 5071A symbol declared with this switch on the command line replaces a 5072symbol with the same name either in a definition file or specified with a 5073switch @code{-D} in the preprocessor data file. 5074 5075This switch is similar to switch @code{-D} of @code{gnatprep}. 5076 5077@item @code{-gnateG} 5078 5079When integrated preprocessing is performed on source file @code{filename.extension}, 5080create or overwrite @code{filename.extension.prep} to contain 5081the result of the preprocessing. 5082For example if the source file is @code{foo.adb} then 5083the output file will be @code{foo.adb.prep}. 5084@end table 5085 5086@node Mixed Language Programming,GNAT and Other Compilation Models,Conditional Compilation,The GNAT Compilation Model 5087@anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{2c}@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{9d} 5088@section Mixed Language Programming 5089 5090 5091@geindex Mixed Language Programming 5092 5093This section describes how to develop a mixed-language program, 5094with a focus on combining Ada with C or C++. 5095 5096@menu 5097* Interfacing to C:: 5098* Calling Conventions:: 5099* Building Mixed Ada and C++ Programs:: 5100* Generating Ada Bindings for C and C++ headers:: 5101* Generating C Headers for Ada Specifications:: 5102 5103@end menu 5104 5105@node Interfacing to C,Calling Conventions,,Mixed Language Programming 5106@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{9e}@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{9f} 5107@subsection Interfacing to C 5108 5109 5110Interfacing Ada with a foreign language such as C involves using 5111compiler directives to import and/or export entity definitions in each 5112language -- using @code{extern} statements in C, for instance, and the 5113@code{Import}, @code{Export}, and @code{Convention} pragmas in Ada. 5114A full treatment of these topics is provided in Appendix B, section 1 5115of the Ada Reference Manual. 5116 5117There are two ways to build a program using GNAT that contains some Ada 5118sources and some foreign language sources, depending on whether or not 5119the main subprogram is written in Ada. Here is a source example with 5120the main subprogram in Ada: 5121 5122@example 5123/* file1.c */ 5124#include <stdio.h> 5125 5126void print_num (int num) 5127@{ 5128 printf ("num is %d.\\n", num); 5129 return; 5130@} 5131@end example 5132 5133@example 5134/* file2.c */ 5135 5136/* num_from_Ada is declared in my_main.adb */ 5137extern int num_from_Ada; 5138 5139int get_num (void) 5140@{ 5141 return num_from_Ada; 5142@} 5143@end example 5144 5145@example 5146-- my_main.adb 5147procedure My_Main is 5148 5149 -- Declare then export an Integer entity called num_from_Ada 5150 My_Num : Integer := 10; 5151 pragma Export (C, My_Num, "num_from_Ada"); 5152 5153 -- Declare an Ada function spec for Get_Num, then use 5154 -- C function get_num for the implementation. 5155 function Get_Num return Integer; 5156 pragma Import (C, Get_Num, "get_num"); 5157 5158 -- Declare an Ada procedure spec for Print_Num, then use 5159 -- C function print_num for the implementation. 5160 procedure Print_Num (Num : Integer); 5161 pragma Import (C, Print_Num, "print_num"); 5162 5163begin 5164 Print_Num (Get_Num); 5165end My_Main; 5166@end example 5167 5168To build this example: 5169 5170 5171@itemize * 5172 5173@item 5174First compile the foreign language files to 5175generate object files: 5176 5177@example 5178$ gcc -c file1.c 5179$ gcc -c file2.c 5180@end example 5181 5182@item 5183Then, compile the Ada units to produce a set of object files and ALI 5184files: 5185 5186@example 5187$ gnatmake -c my_main.adb 5188@end example 5189 5190@item 5191Run the Ada binder on the Ada main program: 5192 5193@example 5194$ gnatbind my_main.ali 5195@end example 5196 5197@item 5198Link the Ada main program, the Ada objects and the other language 5199objects: 5200 5201@example 5202$ gnatlink my_main.ali file1.o file2.o 5203@end example 5204@end itemize 5205 5206The last three steps can be grouped in a single command: 5207 5208@example 5209$ gnatmake my_main.adb -largs file1.o file2.o 5210@end example 5211 5212@geindex Binder output file 5213 5214If the main program is in a language other than Ada, then you may have 5215more than one entry point into the Ada subsystem. You must use a special 5216binder option to generate callable routines that initialize and 5217finalize the Ada units (@ref{a0,,Binding with Non-Ada Main Programs}). 5218Calls to the initialization and finalization routines must be inserted 5219in the main program, or some other appropriate point in the code. The 5220call to initialize the Ada units must occur before the first Ada 5221subprogram is called, and the call to finalize the Ada units must occur 5222after the last Ada subprogram returns. The binder will place the 5223initialization and finalization subprograms into the 5224@code{b~xxx.adb} file where they can be accessed by your C 5225sources. To illustrate, we have the following example: 5226 5227@example 5228/* main.c */ 5229extern void adainit (void); 5230extern void adafinal (void); 5231extern int add (int, int); 5232extern int sub (int, int); 5233 5234int main (int argc, char *argv[]) 5235@{ 5236 int a = 21, b = 7; 5237 5238 adainit(); 5239 5240 /* Should print "21 + 7 = 28" */ 5241 printf ("%d + %d = %d\\n", a, b, add (a, b)); 5242 5243 /* Should print "21 - 7 = 14" */ 5244 printf ("%d - %d = %d\\n", a, b, sub (a, b)); 5245 5246 adafinal(); 5247@} 5248@end example 5249 5250@example 5251-- unit1.ads 5252package Unit1 is 5253 function Add (A, B : Integer) return Integer; 5254 pragma Export (C, Add, "add"); 5255end Unit1; 5256@end example 5257 5258@example 5259-- unit1.adb 5260package body Unit1 is 5261 function Add (A, B : Integer) return Integer is 5262 begin 5263 return A + B; 5264 end Add; 5265end Unit1; 5266@end example 5267 5268@example 5269-- unit2.ads 5270package Unit2 is 5271 function Sub (A, B : Integer) return Integer; 5272 pragma Export (C, Sub, "sub"); 5273end Unit2; 5274@end example 5275 5276@example 5277-- unit2.adb 5278package body Unit2 is 5279 function Sub (A, B : Integer) return Integer is 5280 begin 5281 return A - B; 5282 end Sub; 5283end Unit2; 5284@end example 5285 5286The build procedure for this application is similar to the last 5287example's: 5288 5289 5290@itemize * 5291 5292@item 5293First, compile the foreign language files to generate object files: 5294 5295@example 5296$ gcc -c main.c 5297@end example 5298 5299@item 5300Next, compile the Ada units to produce a set of object files and ALI 5301files: 5302 5303@example 5304$ gnatmake -c unit1.adb 5305$ gnatmake -c unit2.adb 5306@end example 5307 5308@item 5309Run the Ada binder on every generated ALI file. Make sure to use the 5310@code{-n} option to specify a foreign main program: 5311 5312@example 5313$ gnatbind -n unit1.ali unit2.ali 5314@end example 5315 5316@item 5317Link the Ada main program, the Ada objects and the foreign language 5318objects. You need only list the last ALI file here: 5319 5320@example 5321$ gnatlink unit2.ali main.o -o exec_file 5322@end example 5323 5324This procedure yields a binary executable called @code{exec_file}. 5325@end itemize 5326 5327Depending on the circumstances (for example when your non-Ada main object 5328does not provide symbol @code{main}), you may also need to instruct the 5329GNAT linker not to include the standard startup objects by passing the 5330@code{-nostartfiles} switch to @code{gnatlink}. 5331 5332@node Calling Conventions,Building Mixed Ada and C++ Programs,Interfacing to C,Mixed Language Programming 5333@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{a2} 5334@subsection Calling Conventions 5335 5336 5337@geindex Foreign Languages 5338 5339@geindex Calling Conventions 5340 5341GNAT follows standard calling sequence conventions and will thus interface 5342to any other language that also follows these conventions. The following 5343Convention identifiers are recognized by GNAT: 5344 5345@geindex Interfacing to Ada 5346 5347@geindex Other Ada compilers 5348 5349@geindex Convention Ada 5350 5351 5352@table @asis 5353 5354@item @code{Ada} 5355 5356This indicates that the standard Ada calling sequence will be 5357used and all Ada data items may be passed without any limitations in the 5358case where GNAT is used to generate both the caller and callee. It is also 5359possible to mix GNAT generated code and code generated by another Ada 5360compiler. In this case, the data types should be restricted to simple 5361cases, including primitive types. Whether complex data types can be passed 5362depends on the situation. Probably it is safe to pass simple arrays, such 5363as arrays of integers or floats. Records may or may not work, depending 5364on whether both compilers lay them out identically. Complex structures 5365involving variant records, access parameters, tasks, or protected types, 5366are unlikely to be able to be passed. 5367 5368Note that in the case of GNAT running 5369on a platform that supports HP Ada 83, a higher degree of compatibility 5370can be guaranteed, and in particular records are laid out in an identical 5371manner in the two compilers. Note also that if output from two different 5372compilers is mixed, the program is responsible for dealing with elaboration 5373issues. Probably the safest approach is to write the main program in the 5374version of Ada other than GNAT, so that it takes care of its own elaboration 5375requirements, and then call the GNAT-generated adainit procedure to ensure 5376elaboration of the GNAT components. Consult the documentation of the other 5377Ada compiler for further details on elaboration. 5378 5379However, it is not possible to mix the tasking run time of GNAT and 5380HP Ada 83, All the tasking operations must either be entirely within 5381GNAT compiled sections of the program, or entirely within HP Ada 83 5382compiled sections of the program. 5383@end table 5384 5385@geindex Interfacing to Assembly 5386 5387@geindex Convention Assembler 5388 5389 5390@table @asis 5391 5392@item @code{Assembler} 5393 5394Specifies assembler as the convention. In practice this has the 5395same effect as convention Ada (but is not equivalent in the sense of being 5396considered the same convention). 5397@end table 5398 5399@geindex Convention Asm 5400 5401@geindex Asm 5402 5403 5404@table @asis 5405 5406@item @code{Asm} 5407 5408Equivalent to Assembler. 5409 5410@geindex Interfacing to COBOL 5411 5412@geindex Convention COBOL 5413@end table 5414 5415@geindex COBOL 5416 5417 5418@table @asis 5419 5420@item @code{COBOL} 5421 5422Data will be passed according to the conventions described 5423in section B.4 of the Ada Reference Manual. 5424@end table 5425 5426@geindex C 5427 5428@geindex Interfacing to C 5429 5430@geindex Convention C 5431 5432 5433@table @asis 5434 5435@item @code{C} 5436 5437Data will be passed according to the conventions described 5438in section B.3 of the Ada Reference Manual. 5439 5440A note on interfacing to a C 'varargs' function: 5441 5442@quotation 5443 5444@geindex C varargs function 5445 5446@geindex Interfacing to C varargs function 5447 5448@geindex varargs function interfaces 5449 5450In C, @code{varargs} allows a function to take a variable number of 5451arguments. There is no direct equivalent in this to Ada. One 5452approach that can be used is to create a C wrapper for each 5453different profile and then interface to this C wrapper. For 5454example, to print an @code{int} value using @code{printf}, 5455create a C function @code{printfi} that takes two arguments, a 5456pointer to a string and an int, and calls @code{printf}. 5457Then in the Ada program, use pragma @code{Import} to 5458interface to @code{printfi}. 5459 5460It may work on some platforms to directly interface to 5461a @code{varargs} function by providing a specific Ada profile 5462for a particular call. However, this does not work on 5463all platforms, since there is no guarantee that the 5464calling sequence for a two argument normal C function 5465is the same as for calling a @code{varargs} C function with 5466the same two arguments. 5467@end quotation 5468@end table 5469 5470@geindex Convention Default 5471 5472@geindex Default 5473 5474 5475@table @asis 5476 5477@item @code{Default} 5478 5479Equivalent to C. 5480@end table 5481 5482@geindex Convention External 5483 5484@geindex External 5485 5486 5487@table @asis 5488 5489@item @code{External} 5490 5491Equivalent to C. 5492@end table 5493 5494@geindex C++ 5495 5496@geindex Interfacing to C++ 5497 5498@geindex Convention C++ 5499 5500 5501@table @asis 5502 5503@item @code{C_Plus_Plus} (or @code{CPP}) 5504 5505This stands for C++. For most purposes this is identical to C. 5506See the separate description of the specialized GNAT pragmas relating to 5507C++ interfacing for further details. 5508@end table 5509 5510@geindex Fortran 5511 5512@geindex Interfacing to Fortran 5513 5514@geindex Convention Fortran 5515 5516 5517@table @asis 5518 5519@item @code{Fortran} 5520 5521Data will be passed according to the conventions described 5522in section B.5 of the Ada Reference Manual. 5523 5524@item @code{Intrinsic} 5525 5526This applies to an intrinsic operation, as defined in the Ada 5527Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram, 5528this means that the body of the subprogram is provided by the compiler itself, 5529usually by means of an efficient code sequence, and that the user does not 5530supply an explicit body for it. In an application program, the pragma may 5531be applied to the following sets of names: 5532 5533 5534@itemize * 5535 5536@item 5537Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_Arithmetic. 5538The corresponding subprogram declaration must have 5539two formal parameters. The 5540first one must be a signed integer type or a modular type with a binary 5541modulus, and the second parameter must be of type Natural. 5542The return type must be the same as the type of the first argument. The size 5543of this type can only be 8, 16, 32, or 64. 5544 5545@item 5546Binary arithmetic operators: '+', '-', '*', '/'. 5547The corresponding operator declaration must have parameters and result type 5548that have the same root numeric type (for example, all three are long_float 5549types). This simplifies the definition of operations that use type checking 5550to perform dimensional checks: 5551@end itemize 5552 5553@example 5554 type Distance is new Long_Float; 5555 type Time is new Long_Float; 5556 type Velocity is new Long_Float; 5557 function "/" (D : Distance; T : Time) 5558 return Velocity; 5559 pragma Import (Intrinsic, "/"); 5560 5561This common idiom is often programmed with a generic definition and an 5562explicit body. The pragma makes it simpler to introduce such declarations. 5563It incurs no overhead in compilation time or code size, because it is 5564implemented as a single machine instruction. 5565@end example 5566 5567 5568@itemize * 5569 5570@item 5571General subprogram entities. This is used to bind an Ada subprogram 5572declaration to 5573a compiler builtin by name with back-ends where such interfaces are 5574available. A typical example is the set of @code{__builtin} functions 5575exposed by the GCC back-end, as in the following example: 5576 5577@example 5578function builtin_sqrt (F : Float) return Float; 5579pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf"); 5580@end example 5581 5582Most of the GCC builtins are accessible this way, and as for other 5583import conventions (e.g. C), it is the user's responsibility to ensure 5584that the Ada subprogram profile matches the underlying builtin 5585expectations. 5586@end itemize 5587@end table 5588 5589@geindex Stdcall 5590 5591@geindex Convention Stdcall 5592 5593 5594@table @asis 5595 5596@item @code{Stdcall} 5597 5598This is relevant only to Windows implementations of GNAT, 5599and specifies that the @code{Stdcall} calling sequence will be used, 5600as defined by the NT API. Nevertheless, to ease building 5601cross-platform bindings this convention will be handled as a @code{C} calling 5602convention on non-Windows platforms. 5603@end table 5604 5605@geindex DLL 5606 5607@geindex Convention DLL 5608 5609 5610@table @asis 5611 5612@item @code{DLL} 5613 5614This is equivalent to @code{Stdcall}. 5615@end table 5616 5617@geindex Win32 5618 5619@geindex Convention Win32 5620 5621 5622@table @asis 5623 5624@item @code{Win32} 5625 5626This is equivalent to @code{Stdcall}. 5627@end table 5628 5629@geindex Stubbed 5630 5631@geindex Convention Stubbed 5632 5633 5634@table @asis 5635 5636@item @code{Stubbed} 5637 5638This is a special convention that indicates that the compiler 5639should provide a stub body that raises @code{Program_Error}. 5640@end table 5641 5642GNAT additionally provides a useful pragma @code{Convention_Identifier} 5643that can be used to parameterize conventions and allow additional synonyms 5644to be specified. For example if you have legacy code in which the convention 5645identifier Fortran77 was used for Fortran, you can use the configuration 5646pragma: 5647 5648@example 5649pragma Convention_Identifier (Fortran77, Fortran); 5650@end example 5651 5652And from now on the identifier Fortran77 may be used as a convention 5653identifier (for example in an @code{Import} pragma) with the same 5654meaning as Fortran. 5655 5656@node Building Mixed Ada and C++ Programs,Generating Ada Bindings for C and C++ headers,Calling Conventions,Mixed Language Programming 5657@anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{a4} 5658@subsection Building Mixed Ada and C++ Programs 5659 5660 5661A programmer inexperienced with mixed-language development may find that 5662building an application containing both Ada and C++ code can be a 5663challenge. This section gives a few hints that should make this task easier. 5664 5665@menu 5666* Interfacing to C++:: 5667* Linking a Mixed C++ & Ada Program:: 5668* A Simple Example:: 5669* Interfacing with C++ constructors:: 5670* Interfacing with C++ at the Class Level:: 5671 5672@end menu 5673 5674@node Interfacing to C++,Linking a Mixed C++ & Ada Program,,Building Mixed Ada and C++ Programs 5675@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{a6} 5676@subsubsection Interfacing to C++ 5677 5678 5679GNAT supports interfacing with the G++ compiler (or any C++ compiler 5680generating code that is compatible with the G++ Application Binary 5681Interface ---see @indicateurl{http://www.codesourcery.com/archives/cxx-abi}). 5682 5683Interfacing can be done at 3 levels: simple data, subprograms, and 5684classes. In the first two cases, GNAT offers a specific @code{Convention C_Plus_Plus} 5685(or @code{CPP}) that behaves exactly like @code{Convention C}. 5686Usually, C++ mangles the names of subprograms. To generate proper mangled 5687names automatically, see @ref{a7,,Generating Ada Bindings for C and C++ headers}). 5688This problem can also be addressed manually in two ways: 5689 5690 5691@itemize * 5692 5693@item 5694by modifying the C++ code in order to force a C convention using 5695the @code{extern "C"} syntax. 5696 5697@item 5698by figuring out the mangled name (using e.g. @code{nm}) and using it as the 5699Link_Name argument of the pragma import. 5700@end itemize 5701 5702Interfacing at the class level can be achieved by using the GNAT specific 5703pragmas such as @code{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information. 5704 5705@node Linking a Mixed C++ & Ada Program,A Simple Example,Interfacing to C++,Building Mixed Ada and C++ Programs 5706@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{a8}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{a9} 5707@subsubsection Linking a Mixed C++ & Ada Program 5708 5709 5710Usually the linker of the C++ development system must be used to link 5711mixed applications because most C++ systems will resolve elaboration 5712issues (such as calling constructors on global class instances) 5713transparently during the link phase. GNAT has been adapted to ease the 5714use of a foreign linker for the last phase. Three cases can be 5715considered: 5716 5717 5718@itemize * 5719 5720@item 5721Using GNAT and G++ (GNU C++ compiler) from the same GCC installation: 5722The C++ linker can simply be called by using the C++ specific driver 5723called @code{g++}. 5724 5725Note that if the C++ code uses inline functions, you will need to 5726compile your C++ code with the @code{-fkeep-inline-functions} switch in 5727order to provide an existing function implementation that the Ada code can 5728link with. 5729 5730@example 5731$ g++ -c -fkeep-inline-functions file1.C 5732$ g++ -c -fkeep-inline-functions file2.C 5733$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++ 5734@end example 5735 5736@item 5737Using GNAT and G++ from two different GCC installations: If both 5738compilers are on the :envvar`PATH`, the previous method may be used. It is 5739important to note that environment variables such as 5740@geindex C_INCLUDE_PATH 5741@geindex environment variable; C_INCLUDE_PATH 5742@code{C_INCLUDE_PATH}, 5743@geindex GCC_EXEC_PREFIX 5744@geindex environment variable; GCC_EXEC_PREFIX 5745@code{GCC_EXEC_PREFIX}, 5746@geindex BINUTILS_ROOT 5747@geindex environment variable; BINUTILS_ROOT 5748@code{BINUTILS_ROOT}, and 5749@geindex GCC_ROOT 5750@geindex environment variable; GCC_ROOT 5751@code{GCC_ROOT} will affect both compilers 5752at the same time and may make one of the two compilers operate 5753improperly if set during invocation of the wrong compiler. It is also 5754very important that the linker uses the proper @code{libgcc.a} GCC 5755library -- that is, the one from the C++ compiler installation. The 5756implicit link command as suggested in the @code{gnatmake} command 5757from the former example can be replaced by an explicit link command with 5758the full-verbosity option in order to verify which library is used: 5759 5760@example 5761$ gnatbind ada_unit 5762$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ 5763@end example 5764 5765If there is a problem due to interfering environment variables, it can 5766be worked around by using an intermediate script. The following example 5767shows the proper script to use when GNAT has not been installed at its 5768default location and g++ has been installed at its default location: 5769 5770@example 5771$ cat ./my_script 5772#!/bin/sh 5773unset BINUTILS_ROOT 5774unset GCC_ROOT 5775c++ $* 5776$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script 5777@end example 5778 5779@item 5780Using a non-GNU C++ compiler: The commands previously described can be 5781used to insure that the C++ linker is used. Nonetheless, you need to add 5782a few more parameters to the link command line, depending on the exception 5783mechanism used. 5784 5785If the @code{setjmp} / @code{longjmp} exception mechanism is used, only the paths 5786to the @code{libgcc} libraries are required: 5787 5788@example 5789$ cat ./my_script 5790#!/bin/sh 5791CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a 5792$ gnatlink ada_unit file1.o file2.o --LINK=./my_script 5793@end example 5794 5795where CC is the name of the non-GNU C++ compiler. 5796 5797If the "zero cost" exception mechanism is used, and the platform 5798supports automatic registration of exception tables (e.g., Solaris), 5799paths to more objects are required: 5800 5801@example 5802$ cat ./my_script 5803#!/bin/sh 5804CC gcc -print-file-name=crtbegin.o $* \\ 5805gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\ 5806gcc -print-file-name=crtend.o 5807$ gnatlink ada_unit file1.o file2.o --LINK=./my_script 5808@end example 5809 5810If the "zero cost exception" mechanism is used, and the platform 5811doesn't support automatic registration of exception tables (e.g., HP-UX 5812or AIX), the simple approach described above will not work and 5813a pre-linking phase using GNAT will be necessary. 5814@end itemize 5815 5816Another alternative is to use the @code{gprbuild} multi-language builder 5817which has a large knowledge base and knows how to link Ada and C++ code 5818together automatically in most cases. 5819 5820@node A Simple Example,Interfacing with C++ constructors,Linking a Mixed C++ & Ada Program,Building Mixed Ada and C++ Programs 5821@anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{ab} 5822@subsubsection A Simple Example 5823 5824 5825The following example, provided as part of the GNAT examples, shows how 5826to achieve procedural interfacing between Ada and C++ in both 5827directions. The C++ class A has two methods. The first method is exported 5828to Ada by the means of an extern C wrapper function. The second method 5829calls an Ada subprogram. On the Ada side, the C++ calls are modelled by 5830a limited record with a layout comparable to the C++ class. The Ada 5831subprogram, in turn, calls the C++ method. So, starting from the C++ 5832main program, the process passes back and forth between the two 5833languages. 5834 5835Here are the compilation commands: 5836 5837@example 5838$ gnatmake -c simple_cpp_interface 5839$ g++ -c cpp_main.C 5840$ g++ -c ex7.C 5841$ gnatbind -n simple_cpp_interface 5842$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o 5843@end example 5844 5845Here are the corresponding sources: 5846 5847@example 5848//cpp_main.C 5849 5850#include "ex7.h" 5851 5852extern "C" @{ 5853 void adainit (void); 5854 void adafinal (void); 5855 void method1 (A *t); 5856@} 5857 5858void method1 (A *t) 5859@{ 5860 t->method1 (); 5861@} 5862 5863int main () 5864@{ 5865 A obj; 5866 adainit (); 5867 obj.method2 (3030); 5868 adafinal (); 5869@} 5870@end example 5871 5872@example 5873//ex7.h 5874 5875class Origin @{ 5876 public: 5877 int o_value; 5878@}; 5879class A : public Origin @{ 5880 public: 5881 void method1 (void); 5882 void method2 (int v); 5883 A(); 5884 int a_value; 5885@}; 5886@end example 5887 5888@example 5889//ex7.C 5890 5891#include "ex7.h" 5892#include <stdio.h> 5893 5894extern "C" @{ void ada_method2 (A *t, int v);@} 5895 5896void A::method1 (void) 5897@{ 5898 a_value = 2020; 5899 printf ("in A::method1, a_value = %d \\n",a_value); 5900@} 5901 5902void A::method2 (int v) 5903@{ 5904 ada_method2 (this, v); 5905 printf ("in A::method2, a_value = %d \\n",a_value); 5906@} 5907 5908A::A(void) 5909@{ 5910 a_value = 1010; 5911 printf ("in A::A, a_value = %d \\n",a_value); 5912@} 5913@end example 5914 5915@example 5916-- simple_cpp_interface.ads 5917with System; 5918package Simple_Cpp_Interface is 5919 type A is limited 5920 record 5921 Vptr : System.Address; 5922 O_Value : Integer; 5923 A_Value : Integer; 5924 end record; 5925 pragma Convention (C, A); 5926 5927 procedure Method1 (This : in out A); 5928 pragma Import (C, Method1); 5929 5930 procedure Ada_Method2 (This : in out A; V : Integer); 5931 pragma Export (C, Ada_Method2); 5932 5933end Simple_Cpp_Interface; 5934@end example 5935 5936@example 5937-- simple_cpp_interface.adb 5938package body Simple_Cpp_Interface is 5939 5940 procedure Ada_Method2 (This : in out A; V : Integer) is 5941 begin 5942 Method1 (This); 5943 This.A_Value := V; 5944 end Ada_Method2; 5945 5946end Simple_Cpp_Interface; 5947@end example 5948 5949@node Interfacing with C++ constructors,Interfacing with C++ at the Class Level,A Simple Example,Building Mixed Ada and C++ Programs 5950@anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{ad} 5951@subsubsection Interfacing with C++ constructors 5952 5953 5954In order to interface with C++ constructors GNAT provides the 5955@code{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual} 5956for additional information). 5957In this section we present some common uses of C++ constructors 5958in mixed-languages programs in GNAT. 5959 5960Let us assume that we need to interface with the following 5961C++ class: 5962 5963@example 5964class Root @{ 5965public: 5966 int a_value; 5967 int b_value; 5968 virtual int Get_Value (); 5969 Root(); // Default constructor 5970 Root(int v); // 1st non-default constructor 5971 Root(int v, int w); // 2nd non-default constructor 5972@}; 5973@end example 5974 5975For this purpose we can write the following package spec (further 5976information on how to build this spec is available in 5977@ref{ae,,Interfacing with C++ at the Class Level} and 5978@ref{a7,,Generating Ada Bindings for C and C++ headers}). 5979 5980@example 5981with Interfaces.C; use Interfaces.C; 5982package Pkg_Root is 5983 type Root is tagged limited record 5984 A_Value : int; 5985 B_Value : int; 5986 end record; 5987 pragma Import (CPP, Root); 5988 5989 function Get_Value (Obj : Root) return int; 5990 pragma Import (CPP, Get_Value); 5991 5992 function Constructor return Root; 5993 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev"); 5994 5995 function Constructor (v : Integer) return Root; 5996 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei"); 5997 5998 function Constructor (v, w : Integer) return Root; 5999 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii"); 6000end Pkg_Root; 6001@end example 6002 6003On the Ada side the constructor is represented by a function (whose 6004name is arbitrary) that returns the classwide type corresponding to 6005the imported C++ class. Although the constructor is described as a 6006function, it is typically a procedure with an extra implicit argument 6007(the object being initialized) at the implementation level. GNAT 6008issues the appropriate call, whatever it is, to get the object 6009properly initialized. 6010 6011Constructors can only appear in the following contexts: 6012 6013 6014@itemize * 6015 6016@item 6017On the right side of an initialization of an object of type @code{T}. 6018 6019@item 6020On the right side of an initialization of a record component of type @code{T}. 6021 6022@item 6023In an Ada 2005 limited aggregate. 6024 6025@item 6026In an Ada 2005 nested limited aggregate. 6027 6028@item 6029In an Ada 2005 limited aggregate that initializes an object built in 6030place by an extended return statement. 6031@end itemize 6032 6033In a declaration of an object whose type is a class imported from C++, 6034either the default C++ constructor is implicitly called by GNAT, or 6035else the required C++ constructor must be explicitly called in the 6036expression that initializes the object. For example: 6037 6038@example 6039Obj1 : Root; 6040Obj2 : Root := Constructor; 6041Obj3 : Root := Constructor (v => 10); 6042Obj4 : Root := Constructor (30, 40); 6043@end example 6044 6045The first two declarations are equivalent: in both cases the default C++ 6046constructor is invoked (in the former case the call to the constructor is 6047implicit, and in the latter case the call is explicit in the object 6048declaration). @code{Obj3} is initialized by the C++ non-default constructor 6049that takes an integer argument, and @code{Obj4} is initialized by the 6050non-default C++ constructor that takes two integers. 6051 6052Let us derive the imported C++ class in the Ada side. For example: 6053 6054@example 6055type DT is new Root with record 6056 C_Value : Natural := 2009; 6057end record; 6058@end example 6059 6060In this case the components DT inherited from the C++ side must be 6061initialized by a C++ constructor, and the additional Ada components 6062of type DT are initialized by GNAT. The initialization of such an 6063object is done either by default, or by means of a function returning 6064an aggregate of type DT, or by means of an extension aggregate. 6065 6066@example 6067Obj5 : DT; 6068Obj6 : DT := Function_Returning_DT (50); 6069Obj7 : DT := (Constructor (30,40) with C_Value => 50); 6070@end example 6071 6072The declaration of @code{Obj5} invokes the default constructors: the 6073C++ default constructor of the parent type takes care of the initialization 6074of the components inherited from Root, and GNAT takes care of the default 6075initialization of the additional Ada components of type DT (that is, 6076@code{C_Value} is initialized to value 2009). The order of invocation of 6077the constructors is consistent with the order of elaboration required by 6078Ada and C++. That is, the constructor of the parent type is always called 6079before the constructor of the derived type. 6080 6081Let us now consider a record that has components whose type is imported 6082from C++. For example: 6083 6084@example 6085type Rec1 is limited record 6086 Data1 : Root := Constructor (10); 6087 Value : Natural := 1000; 6088end record; 6089 6090type Rec2 (D : Integer := 20) is limited record 6091 Rec : Rec1; 6092 Data2 : Root := Constructor (D, 30); 6093end record; 6094@end example 6095 6096The initialization of an object of type @code{Rec2} will call the 6097non-default C++ constructors specified for the imported components. 6098For example: 6099 6100@example 6101Obj8 : Rec2 (40); 6102@end example 6103 6104Using Ada 2005 we can use limited aggregates to initialize an object 6105invoking C++ constructors that differ from those specified in the type 6106declarations. For example: 6107 6108@example 6109Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16), 6110 others => <>), 6111 others => <>); 6112@end example 6113 6114The above declaration uses an Ada 2005 limited aggregate to 6115initialize @code{Obj9}, and the C++ constructor that has two integer 6116arguments is invoked to initialize the @code{Data1} component instead 6117of the constructor specified in the declaration of type @code{Rec1}. In 6118Ada 2005 the box in the aggregate indicates that unspecified components 6119are initialized using the expression (if any) available in the component 6120declaration. That is, in this case discriminant @code{D} is initialized 6121to value @code{20}, @code{Value} is initialized to value 1000, and the 6122non-default C++ constructor that handles two integers takes care of 6123initializing component @code{Data2} with values @code{20,30}. 6124 6125In Ada 2005 we can use the extended return statement to build the Ada 6126equivalent to C++ non-default constructors. For example: 6127 6128@example 6129function Constructor (V : Integer) return Rec2 is 6130begin 6131 return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20), 6132 others => <>), 6133 others => <>) do 6134 -- Further actions required for construction of 6135 -- objects of type Rec2 6136 ... 6137 end record; 6138end Constructor; 6139@end example 6140 6141In this example the extended return statement construct is used to 6142build in place the returned object whose components are initialized 6143by means of a limited aggregate. Any further action associated with 6144the constructor can be placed inside the construct. 6145 6146@node Interfacing with C++ at the Class Level,,Interfacing with C++ constructors,Building Mixed Ada and C++ Programs 6147@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{ae}@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{af} 6148@subsubsection Interfacing with C++ at the Class Level 6149 6150 6151In this section we demonstrate the GNAT features for interfacing with 6152C++ by means of an example making use of Ada 2005 abstract interface 6153types. This example consists of a classification of animals; classes 6154have been used to model our main classification of animals, and 6155interfaces provide support for the management of secondary 6156classifications. We first demonstrate a case in which the types and 6157constructors are defined on the C++ side and imported from the Ada 6158side, and latter the reverse case. 6159 6160The root of our derivation will be the @code{Animal} class, with a 6161single private attribute (the @code{Age} of the animal), a constructor, 6162and two public primitives to set and get the value of this attribute. 6163 6164@example 6165class Animal @{ 6166 public: 6167 virtual void Set_Age (int New_Age); 6168 virtual int Age (); 6169 Animal() @{Age_Count = 0;@}; 6170 private: 6171 int Age_Count; 6172@}; 6173@end example 6174 6175Abstract interface types are defined in C++ by means of classes with pure 6176virtual functions and no data members. In our example we will use two 6177interfaces that provide support for the common management of @code{Carnivore} 6178and @code{Domestic} animals: 6179 6180@example 6181class Carnivore @{ 6182public: 6183 virtual int Number_Of_Teeth () = 0; 6184@}; 6185 6186class Domestic @{ 6187public: 6188 virtual void Set_Owner (char* Name) = 0; 6189@}; 6190@end example 6191 6192Using these declarations, we can now say that a @code{Dog} is an animal that is 6193both Carnivore and Domestic, that is: 6194 6195@example 6196class Dog : Animal, Carnivore, Domestic @{ 6197 public: 6198 virtual int Number_Of_Teeth (); 6199 virtual void Set_Owner (char* Name); 6200 6201 Dog(); // Constructor 6202 private: 6203 int Tooth_Count; 6204 char *Owner; 6205@}; 6206@end example 6207 6208In the following examples we will assume that the previous declarations are 6209located in a file named @code{animals.h}. The following package demonstrates 6210how to import these C++ declarations from the Ada side: 6211 6212@example 6213with Interfaces.C.Strings; use Interfaces.C.Strings; 6214package Animals is 6215 type Carnivore is limited interface; 6216 pragma Convention (C_Plus_Plus, Carnivore); 6217 function Number_Of_Teeth (X : Carnivore) 6218 return Natural is abstract; 6219 6220 type Domestic is limited interface; 6221 pragma Convention (C_Plus_Plus, Domestic); 6222 procedure Set_Owner 6223 (X : in out Domestic; 6224 Name : Chars_Ptr) is abstract; 6225 6226 type Animal is tagged limited record 6227 Age : Natural; 6228 end record; 6229 pragma Import (C_Plus_Plus, Animal); 6230 6231 procedure Set_Age (X : in out Animal; Age : Integer); 6232 pragma Import (C_Plus_Plus, Set_Age); 6233 6234 function Age (X : Animal) return Integer; 6235 pragma Import (C_Plus_Plus, Age); 6236 6237 function New_Animal return Animal; 6238 pragma CPP_Constructor (New_Animal); 6239 pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev"); 6240 6241 type Dog is new Animal and Carnivore and Domestic with record 6242 Tooth_Count : Natural; 6243 Owner : Chars_Ptr; 6244 end record; 6245 pragma Import (C_Plus_Plus, Dog); 6246 6247 function Number_Of_Teeth (A : Dog) return Natural; 6248 pragma Import (C_Plus_Plus, Number_Of_Teeth); 6249 6250 procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); 6251 pragma Import (C_Plus_Plus, Set_Owner); 6252 6253 function New_Dog return Dog; 6254 pragma CPP_Constructor (New_Dog); 6255 pragma Import (CPP, New_Dog, "_ZN3DogC2Ev"); 6256end Animals; 6257@end example 6258 6259Thanks to the compatibility between GNAT run-time structures and the C++ ABI, 6260interfacing with these C++ classes is easy. The only requirement is that all 6261the primitives and components must be declared exactly in the same order in 6262the two languages. 6263 6264Regarding the abstract interfaces, we must indicate to the GNAT compiler by 6265means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass 6266the arguments to the called primitives will be the same as for C++. For the 6267imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus} 6268to indicate that they have been defined on the C++ side; this is required 6269because the dispatch table associated with these tagged types will be built 6270in the C++ side and therefore will not contain the predefined Ada primitives 6271which Ada would otherwise expect. 6272 6273As the reader can see there is no need to indicate the C++ mangled names 6274associated with each subprogram because it is assumed that all the calls to 6275these primitives will be dispatching calls. The only exception is the 6276constructor, which must be registered with the compiler by means of 6277@code{pragma CPP_Constructor} and needs to provide its associated C++ 6278mangled name because the Ada compiler generates direct calls to it. 6279 6280With the above packages we can now declare objects of type Dog on the Ada side 6281and dispatch calls to the corresponding subprograms on the C++ side. We can 6282also extend the tagged type Dog with further fields and primitives, and 6283override some of its C++ primitives on the Ada side. For example, here we have 6284a type derivation defined on the Ada side that inherits all the dispatching 6285primitives of the ancestor from the C++ side. 6286 6287@example 6288with Animals; use Animals; 6289package Vaccinated_Animals is 6290 type Vaccinated_Dog is new Dog with null record; 6291 function Vaccination_Expired (A : Vaccinated_Dog) return Boolean; 6292end Vaccinated_Animals; 6293@end example 6294 6295It is important to note that, because of the ABI compatibility, the programmer 6296does not need to add any further information to indicate either the object 6297layout or the dispatch table entry associated with each dispatching operation. 6298 6299Now let us define all the types and constructors on the Ada side and export 6300them to C++, using the same hierarchy of our previous example: 6301 6302@example 6303with Interfaces.C.Strings; 6304use Interfaces.C.Strings; 6305package Animals is 6306 type Carnivore is limited interface; 6307 pragma Convention (C_Plus_Plus, Carnivore); 6308 function Number_Of_Teeth (X : Carnivore) 6309 return Natural is abstract; 6310 6311 type Domestic is limited interface; 6312 pragma Convention (C_Plus_Plus, Domestic); 6313 procedure Set_Owner 6314 (X : in out Domestic; 6315 Name : Chars_Ptr) is abstract; 6316 6317 type Animal is tagged record 6318 Age : Natural; 6319 end record; 6320 pragma Convention (C_Plus_Plus, Animal); 6321 6322 procedure Set_Age (X : in out Animal; Age : Integer); 6323 pragma Export (C_Plus_Plus, Set_Age); 6324 6325 function Age (X : Animal) return Integer; 6326 pragma Export (C_Plus_Plus, Age); 6327 6328 function New_Animal return Animal'Class; 6329 pragma Export (C_Plus_Plus, New_Animal); 6330 6331 type Dog is new Animal and Carnivore and Domestic with record 6332 Tooth_Count : Natural; 6333 Owner : String (1 .. 30); 6334 end record; 6335 pragma Convention (C_Plus_Plus, Dog); 6336 6337 function Number_Of_Teeth (A : Dog) return Natural; 6338 pragma Export (C_Plus_Plus, Number_Of_Teeth); 6339 6340 procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); 6341 pragma Export (C_Plus_Plus, Set_Owner); 6342 6343 function New_Dog return Dog'Class; 6344 pragma Export (C_Plus_Plus, New_Dog); 6345end Animals; 6346@end example 6347 6348Compared with our previous example the only differences are the use of 6349@code{pragma Convention} (instead of @code{pragma Import}), and the use of 6350@code{pragma Export} to indicate to the GNAT compiler that the primitives will 6351be available to C++. Thanks to the ABI compatibility, on the C++ side there is 6352nothing else to be done; as explained above, the only requirement is that all 6353the primitives and components are declared in exactly the same order. 6354 6355For completeness, let us see a brief C++ main program that uses the 6356declarations available in @code{animals.h} (presented in our first example) to 6357import and use the declarations from the Ada side, properly initializing and 6358finalizing the Ada run-time system along the way: 6359 6360@example 6361#include "animals.h" 6362#include <iostream> 6363using namespace std; 6364 6365void Check_Carnivore (Carnivore *obj) @{...@} 6366void Check_Domestic (Domestic *obj) @{...@} 6367void Check_Animal (Animal *obj) @{...@} 6368void Check_Dog (Dog *obj) @{...@} 6369 6370extern "C" @{ 6371 void adainit (void); 6372 void adafinal (void); 6373 Dog* new_dog (); 6374@} 6375 6376void test () 6377@{ 6378 Dog *obj = new_dog(); // Ada constructor 6379 Check_Carnivore (obj); // Check secondary DT 6380 Check_Domestic (obj); // Check secondary DT 6381 Check_Animal (obj); // Check primary DT 6382 Check_Dog (obj); // Check primary DT 6383@} 6384 6385int main () 6386@{ 6387 adainit (); test(); adafinal (); 6388 return 0; 6389@} 6390@end example 6391 6392@node Generating Ada Bindings for C and C++ headers,Generating C Headers for Ada Specifications,Building Mixed Ada and C++ Programs,Mixed Language Programming 6393@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{b0}@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{a7} 6394@subsection Generating Ada Bindings for C and C++ headers 6395 6396 6397@geindex Binding generation (for C and C++ headers) 6398 6399@geindex C headers (binding generation) 6400 6401@geindex C++ headers (binding generation) 6402 6403GNAT includes a binding generator for C and C++ headers which is 6404intended to do 95% of the tedious work of generating Ada specs from C 6405or C++ header files. 6406 6407Note that this capability is not intended to generate 100% correct Ada specs, 6408and will is some cases require manual adjustments, although it can often 6409be used out of the box in practice. 6410 6411Some of the known limitations include: 6412 6413 6414@itemize * 6415 6416@item 6417only very simple character constant macros are translated into Ada 6418constants. Function macros (macros with arguments) are partially translated 6419as comments, to be completed manually if needed. 6420 6421@item 6422some extensions (e.g. vector types) are not supported 6423 6424@item 6425pointers to pointers or complex structures are mapped to System.Address 6426 6427@item 6428identifiers with identical name (except casing) will generate compilation 6429errors (e.g. @code{shm_get} vs @code{SHM_GET}). 6430@end itemize 6431 6432The code is generated using Ada 2012 syntax, which makes it easier to interface 6433with other languages. In most cases you can still use the generated binding 6434even if your code is compiled using earlier versions of Ada (e.g. @code{-gnat95}). 6435 6436@menu 6437* Running the Binding Generator:: 6438* Generating Bindings for C++ Headers:: 6439* Switches:: 6440 6441@end menu 6442 6443@node Running the Binding Generator,Generating Bindings for C++ Headers,,Generating Ada Bindings for C and C++ headers 6444@anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{b1}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{b2} 6445@subsubsection Running the Binding Generator 6446 6447 6448The binding generator is part of the @code{gcc} compiler and can be 6449invoked via the @code{-fdump-ada-spec} switch, which will generate Ada 6450spec files for the header files specified on the command line, and all 6451header files needed by these files transitively. For example: 6452 6453@example 6454$ g++ -c -fdump-ada-spec -C /usr/include/time.h 6455$ gcc -c *.ads 6456@end example 6457 6458will generate, under GNU/Linux, the following files: @code{time_h.ads}, 6459@code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which 6460correspond to the files @code{/usr/include/time.h}, 6461@code{/usr/include/bits/time.h}, etc..., and will then compile these Ada specs 6462in Ada 2005 mode. 6463 6464The @code{-C} switch tells @code{gcc} to extract comments from headers, 6465and will attempt to generate corresponding Ada comments. 6466 6467If you want to generate a single Ada file and not the transitive closure, you 6468can use instead the @code{-fdump-ada-spec-slim} switch. 6469 6470You can optionally specify a parent unit, of which all generated units will 6471be children, using @code{-fada-spec-parent=@emph{unit}}. 6472 6473Note that we recommend when possible to use the @emph{g++} driver to 6474generate bindings, even for most C headers, since this will in general 6475generate better Ada specs. For generating bindings for C++ headers, it is 6476mandatory to use the @emph{g++} command, or @emph{gcc -x c++} which 6477is equivalent in this case. If @emph{g++} cannot work on your C headers 6478because of incompatibilities between C and C++, then you can fallback to 6479@code{gcc} instead. 6480 6481For an example of better bindings generated from the C++ front-end, 6482the name of the parameters (when available) are actually ignored by the C 6483front-end. Consider the following C header: 6484 6485@example 6486extern void foo (int variable); 6487@end example 6488 6489with the C front-end, @code{variable} is ignored, and the above is handled as: 6490 6491@example 6492extern void foo (int); 6493@end example 6494 6495generating a generic: 6496 6497@example 6498procedure foo (param1 : int); 6499@end example 6500 6501with the C++ front-end, the name is available, and we generate: 6502 6503@example 6504procedure foo (variable : int); 6505@end example 6506 6507In some cases, the generated bindings will be more complete or more meaningful 6508when defining some macros, which you can do via the @code{-D} switch. This 6509is for example the case with @code{Xlib.h} under GNU/Linux: 6510 6511@example 6512$ g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h 6513@end example 6514 6515The above will generate more complete bindings than a straight call without 6516the @code{-DXLIB_ILLEGAL_ACCESS} switch. 6517 6518In other cases, it is not possible to parse a header file in a stand-alone 6519manner, because other include files need to be included first. In this 6520case, the solution is to create a small header file including the needed 6521@code{#include} and possible @code{#define} directives. For example, to 6522generate Ada bindings for @code{readline/readline.h}, you need to first 6523include @code{stdio.h}, so you can create a file with the following two 6524lines in e.g. @code{readline1.h}: 6525 6526@example 6527#include <stdio.h> 6528#include <readline/readline.h> 6529@end example 6530 6531and then generate Ada bindings from this file: 6532 6533@example 6534$ g++ -c -fdump-ada-spec readline1.h 6535@end example 6536 6537@node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers 6538@anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{b3}@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{b4} 6539@subsubsection Generating Bindings for C++ Headers 6540 6541 6542Generating bindings for C++ headers is done using the same options, always 6543with the @emph{g++} compiler. Note that generating Ada spec from C++ headers is a 6544much more complex job and support for C++ headers is much more limited that 6545support for C headers. As a result, you will need to modify the resulting 6546bindings by hand more extensively when using C++ headers. 6547 6548In this mode, C++ classes will be mapped to Ada tagged types, constructors 6549will be mapped using the @code{CPP_Constructor} pragma, and when possible, 6550multiple inheritance of abstract classes will be mapped to Ada interfaces 6551(see the @emph{Interfacing to C++} section in the @cite{GNAT Reference Manual} 6552for additional information on interfacing to C++). 6553 6554For example, given the following C++ header file: 6555 6556@example 6557class Carnivore @{ 6558public: 6559 virtual int Number_Of_Teeth () = 0; 6560@}; 6561 6562class Domestic @{ 6563public: 6564 virtual void Set_Owner (char* Name) = 0; 6565@}; 6566 6567class Animal @{ 6568public: 6569 int Age_Count; 6570 virtual void Set_Age (int New_Age); 6571@}; 6572 6573class Dog : Animal, Carnivore, Domestic @{ 6574 public: 6575 int Tooth_Count; 6576 char *Owner; 6577 6578 virtual int Number_Of_Teeth (); 6579 virtual void Set_Owner (char* Name); 6580 6581 Dog(); 6582@}; 6583@end example 6584 6585The corresponding Ada code is generated: 6586 6587@example 6588package Class_Carnivore is 6589 type Carnivore is limited interface; 6590 pragma Import (CPP, Carnivore); 6591 6592 function Number_Of_Teeth (this : access Carnivore) return int is abstract; 6593end; 6594use Class_Carnivore; 6595 6596package Class_Domestic is 6597 type Domestic is limited interface; 6598 pragma Import (CPP, Domestic); 6599 6600 procedure Set_Owner 6601 (this : access Domestic; 6602 Name : Interfaces.C.Strings.chars_ptr) is abstract; 6603end; 6604use Class_Domestic; 6605 6606package Class_Animal is 6607 type Animal is tagged limited record 6608 Age_Count : aliased int; 6609 end record; 6610 pragma Import (CPP, Animal); 6611 6612 procedure Set_Age (this : access Animal; New_Age : int); 6613 pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi"); 6614end; 6615use Class_Animal; 6616 6617package Class_Dog is 6618 type Dog is new Animal and Carnivore and Domestic with record 6619 Tooth_Count : aliased int; 6620 Owner : Interfaces.C.Strings.chars_ptr; 6621 end record; 6622 pragma Import (CPP, Dog); 6623 6624 function Number_Of_Teeth (this : access Dog) return int; 6625 pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv"); 6626 6627 procedure Set_Owner 6628 (this : access Dog; Name : Interfaces.C.Strings.chars_ptr); 6629 pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc"); 6630 6631 function New_Dog return Dog; 6632 pragma CPP_Constructor (New_Dog); 6633 pragma Import (CPP, New_Dog, "_ZN3DogC1Ev"); 6634end; 6635use Class_Dog; 6636@end example 6637 6638@node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers 6639@anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{b6} 6640@subsubsection Switches 6641 6642 6643@geindex -fdump-ada-spec (gcc) 6644 6645 6646@table @asis 6647 6648@item @code{-fdump-ada-spec} 6649 6650Generate Ada spec files for the given header files transitively (including 6651all header files that these headers depend upon). 6652@end table 6653 6654@geindex -fdump-ada-spec-slim (gcc) 6655 6656 6657@table @asis 6658 6659@item @code{-fdump-ada-spec-slim} 6660 6661Generate Ada spec files for the header files specified on the command line 6662only. 6663@end table 6664 6665@geindex -fada-spec-parent (gcc) 6666 6667 6668@table @asis 6669 6670@item @code{-fada-spec-parent=@emph{unit}} 6671 6672Specifies that all files generated by @code{-fdump-ada-spec} are 6673to be child units of the specified parent unit. 6674@end table 6675 6676@geindex -C (gcc) 6677 6678 6679@table @asis 6680 6681@item @code{-C} 6682 6683Extract comments from headers and generate Ada comments in the Ada spec files. 6684@end table 6685 6686@node Generating C Headers for Ada Specifications,,Generating Ada Bindings for C and C++ headers,Mixed Language Programming 6687@anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{b7}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{b8} 6688@subsection Generating C Headers for Ada Specifications 6689 6690 6691@geindex Binding generation (for Ada specs) 6692 6693@geindex C headers (binding generation) 6694 6695GNAT includes a C header generator for Ada specifications which supports 6696Ada types that have a direct mapping to C types. This includes in particular 6697support for: 6698 6699 6700@itemize * 6701 6702@item 6703Scalar types 6704 6705@item 6706Constrained arrays 6707 6708@item 6709Records (untagged) 6710 6711@item 6712Composition of the above types 6713 6714@item 6715Constant declarations 6716 6717@item 6718Object declarations 6719 6720@item 6721Subprogram declarations 6722@end itemize 6723 6724@menu 6725* Running the C Header Generator:: 6726 6727@end menu 6728 6729@node Running the C Header Generator,,,Generating C Headers for Ada Specifications 6730@anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{b9} 6731@subsubsection Running the C Header Generator 6732 6733 6734The C header generator is part of the GNAT compiler and can be invoked via 6735the @code{-gnatceg} combination of switches, which will generate a @code{.h} 6736file corresponding to the given input file (Ada spec or body). Note that 6737only spec files are processed in any case, so giving a spec or a body file 6738as input is equivalent. For example: 6739 6740@example 6741$ gcc -c -gnatceg pack1.ads 6742@end example 6743 6744will generate a self-contained file called @code{pack1.h} including 6745common definitions from the Ada Standard package, followed by the 6746definitions included in @code{pack1.ads}, as well as all the other units 6747withed by this file. 6748 6749For instance, given the following Ada files: 6750 6751@example 6752package Pack2 is 6753 type Int is range 1 .. 10; 6754end Pack2; 6755@end example 6756 6757@example 6758with Pack2; 6759 6760package Pack1 is 6761 type Rec is record 6762 Field1, Field2 : Pack2.Int; 6763 end record; 6764 6765 Global : Rec := (1, 2); 6766 6767 procedure Proc1 (R : Rec); 6768 procedure Proc2 (R : in out Rec); 6769end Pack1; 6770@end example 6771 6772The above @code{gcc} command will generate the following @code{pack1.h} file: 6773 6774@example 6775/* Standard definitions skipped */ 6776#ifndef PACK2_ADS 6777#define PACK2_ADS 6778typedef short_short_integer pack2__TintB; 6779typedef pack2__TintB pack2__int; 6780#endif /* PACK2_ADS */ 6781 6782#ifndef PACK1_ADS 6783#define PACK1_ADS 6784typedef struct _pack1__rec @{ 6785 pack2__int field1; 6786 pack2__int field2; 6787@} pack1__rec; 6788extern pack1__rec pack1__global; 6789extern void pack1__proc1(const pack1__rec r); 6790extern void pack1__proc2(pack1__rec *r); 6791#endif /* PACK1_ADS */ 6792@end example 6793 6794You can then @code{include} @code{pack1.h} from a C source file and use the types, 6795call subprograms, reference objects, and constants. 6796 6797@node GNAT and Other Compilation Models,Using GNAT Files with External Tools,Mixed Language Programming,The GNAT Compilation Model 6798@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{ba}@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{2d} 6799@section GNAT and Other Compilation Models 6800 6801 6802This section compares the GNAT model with the approaches taken in 6803other environents, first the C/C++ model and then the mechanism that 6804has been used in other Ada systems, in particular those traditionally 6805used for Ada 83. 6806 6807@menu 6808* Comparison between GNAT and C/C++ Compilation Models:: 6809* Comparison between GNAT and Conventional Ada Library Models:: 6810 6811@end menu 6812 6813@node Comparison between GNAT and C/C++ Compilation Models,Comparison between GNAT and Conventional Ada Library Models,,GNAT and Other Compilation Models 6814@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{bc} 6815@subsection Comparison between GNAT and C/C++ Compilation Models 6816 6817 6818The GNAT model of compilation is close to the C and C++ models. You can 6819think of Ada specs as corresponding to header files in C. As in C, you 6820don't need to compile specs; they are compiled when they are used. The 6821Ada @emph{with} is similar in effect to the @code{#include} of a C 6822header. 6823 6824One notable difference is that, in Ada, you may compile specs separately 6825to check them for semantic and syntactic accuracy. This is not always 6826possible with C headers because they are fragments of programs that have 6827less specific syntactic or semantic rules. 6828 6829The other major difference is the requirement for running the binder, 6830which performs two important functions. First, it checks for 6831consistency. In C or C++, the only defense against assembling 6832inconsistent programs lies outside the compiler, in a makefile, for 6833example. The binder satisfies the Ada requirement that it be impossible 6834to construct an inconsistent program when the compiler is used in normal 6835mode. 6836 6837@geindex Elaboration order control 6838 6839The other important function of the binder is to deal with elaboration 6840issues. There are also elaboration issues in C++ that are handled 6841automatically. This automatic handling has the advantage of being 6842simpler to use, but the C++ programmer has no control over elaboration. 6843Where @code{gnatbind} might complain there was no valid order of 6844elaboration, a C++ compiler would simply construct a program that 6845malfunctioned at run time. 6846 6847@node Comparison between GNAT and Conventional Ada Library Models,,Comparison between GNAT and C/C++ Compilation Models,GNAT and Other Compilation Models 6848@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{be} 6849@subsection Comparison between GNAT and Conventional Ada Library Models 6850 6851 6852This section is intended for Ada programmers who have 6853used an Ada compiler implementing the traditional Ada library 6854model, as described in the Ada Reference Manual. 6855 6856@geindex GNAT library 6857 6858In GNAT, there is no 'library' in the normal sense. Instead, the set of 6859source files themselves acts as the library. Compiling Ada programs does 6860not generate any centralized information, but rather an object file and 6861a ALI file, which are of interest only to the binder and linker. 6862In a traditional system, the compiler reads information not only from 6863the source file being compiled, but also from the centralized library. 6864This means that the effect of a compilation depends on what has been 6865previously compiled. In particular: 6866 6867 6868@itemize * 6869 6870@item 6871When a unit is @emph{with}ed, the unit seen by the compiler corresponds 6872to the version of the unit most recently compiled into the library. 6873 6874@item 6875Inlining is effective only if the necessary body has already been 6876compiled into the library. 6877 6878@item 6879Compiling a unit may obsolete other units in the library. 6880@end itemize 6881 6882In GNAT, compiling one unit never affects the compilation of any other 6883units because the compiler reads only source files. Only changes to source 6884files can affect the results of a compilation. In particular: 6885 6886 6887@itemize * 6888 6889@item 6890When a unit is @emph{with}ed, the unit seen by the compiler corresponds 6891to the source version of the unit that is currently accessible to the 6892compiler. 6893 6894@geindex Inlining 6895 6896@item 6897Inlining requires the appropriate source files for the package or 6898subprogram bodies to be available to the compiler. Inlining is always 6899effective, independent of the order in which units are compiled. 6900 6901@item 6902Compiling a unit never affects any other compilations. The editing of 6903sources may cause previous compilations to be out of date if they 6904depended on the source file being modified. 6905@end itemize 6906 6907The most important result of these differences is that order of compilation 6908is never significant in GNAT. There is no situation in which one is 6909required to do one compilation before another. What shows up as order of 6910compilation requirements in the traditional Ada library becomes, in 6911GNAT, simple source dependencies; in other words, there is only a set 6912of rules saying what source files must be present when a file is 6913compiled. 6914 6915@node Using GNAT Files with External Tools,,GNAT and Other Compilation Models,The GNAT Compilation Model 6916@anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{2e}@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{bf} 6917@section Using GNAT Files with External Tools 6918 6919 6920This section explains how files that are produced by GNAT may be 6921used with tools designed for other languages. 6922 6923@menu 6924* Using Other Utility Programs with GNAT:: 6925* The External Symbol Naming Scheme of GNAT:: 6926 6927@end menu 6928 6929@node Using Other Utility Programs with GNAT,The External Symbol Naming Scheme of GNAT,,Using GNAT Files with External Tools 6930@anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{c0}@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{c1} 6931@subsection Using Other Utility Programs with GNAT 6932 6933 6934The object files generated by GNAT are in standard system format and in 6935particular the debugging information uses this format. This means 6936programs generated by GNAT can be used with existing utilities that 6937depend on these formats. 6938 6939In general, any utility program that works with C will also often work with 6940Ada programs generated by GNAT. This includes software utilities such as 6941gprof (a profiling program), gdb (the FSF debugger), and utilities such 6942as Purify. 6943 6944@node The External Symbol Naming Scheme of GNAT,,Using Other Utility Programs with GNAT,Using GNAT Files with External Tools 6945@anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{c2}@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{c3} 6946@subsection The External Symbol Naming Scheme of GNAT 6947 6948 6949In order to interpret the output from GNAT, when using tools that are 6950originally intended for use with other languages, it is useful to 6951understand the conventions used to generate link names from the Ada 6952entity names. 6953 6954All link names are in all lowercase letters. With the exception of library 6955procedure names, the mechanism used is simply to use the full expanded 6956Ada name with dots replaced by double underscores. For example, suppose 6957we have the following package spec: 6958 6959@example 6960package QRS is 6961 MN : Integer; 6962end QRS; 6963@end example 6964 6965@geindex pragma Export 6966 6967The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so 6968the corresponding link name is @code{qrs__mn}. 6969Of course if a @code{pragma Export} is used this may be overridden: 6970 6971@example 6972package Exports is 6973 Var1 : Integer; 6974 pragma Export (Var1, C, External_Name => "var1_name"); 6975 Var2 : Integer; 6976 pragma Export (Var2, C, Link_Name => "var2_link_name"); 6977end Exports; 6978@end example 6979 6980In this case, the link name for @code{Var1} is whatever link name the 6981C compiler would assign for the C function @code{var1_name}. This typically 6982would be either @code{var1_name} or @code{_var1_name}, depending on operating 6983system conventions, but other possibilities exist. The link name for 6984@code{Var2} is @code{var2_link_name}, and this is not operating system 6985dependent. 6986 6987One exception occurs for library level procedures. A potential ambiguity 6988arises between the required name @code{_main} for the C main program, 6989and the name we would otherwise assign to an Ada library level procedure 6990called @code{Main} (which might well not be the main program). 6991 6992To avoid this ambiguity, we attach the prefix @code{_ada_} to such 6993names. So if we have a library level procedure such as: 6994 6995@example 6996procedure Hello (S : String); 6997@end example 6998 6999the external name of this procedure will be @code{_ada_hello}. 7000 7001@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit 7002 7003@node Building Executable Programs with GNAT,GNAT Utility Programs,The GNAT Compilation Model,Top 7004@anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{c4}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{c5} 7005@chapter Building Executable Programs with GNAT 7006 7007 7008This chapter describes first the gnatmake tool 7009(@ref{c6,,Building with gnatmake}), 7010which automatically determines the set of sources 7011needed by an Ada compilation unit and executes the necessary 7012(re)compilations, binding and linking. 7013It also explains how to use each tool individually: the 7014compiler (gcc, see @ref{c7,,Compiling with gcc}), 7015binder (gnatbind, see @ref{c8,,Binding with gnatbind}), 7016and linker (gnatlink, see @ref{c9,,Linking with gnatlink}) 7017to build executable programs. 7018Finally, this chapter provides examples of 7019how to make use of the general GNU make mechanism 7020in a GNAT context (see @ref{70,,Using the GNU make Utility}). 7021 7022 7023@menu 7024* Building with gnatmake:: 7025* Compiling with gcc:: 7026* Compiler Switches:: 7027* Linker Switches:: 7028* Binding with gnatbind:: 7029* Linking with gnatlink:: 7030* Using the GNU make Utility:: 7031 7032@end menu 7033 7034@node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT 7035@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{c6}@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{ca} 7036@section Building with @code{gnatmake} 7037 7038 7039@geindex gnatmake 7040 7041A typical development cycle when working on an Ada program consists of 7042the following steps: 7043 7044 7045@enumerate 7046 7047@item 7048Edit some sources to fix bugs; 7049 7050@item 7051Add enhancements; 7052 7053@item 7054Compile all sources affected; 7055 7056@item 7057Rebind and relink; and 7058 7059@item 7060Test. 7061@end enumerate 7062 7063@geindex Dependency rules (compilation) 7064 7065The third step in particular can be tricky, because not only do the modified 7066files have to be compiled, but any files depending on these files must also be 7067recompiled. The dependency rules in Ada can be quite complex, especially 7068in the presence of overloading, @code{use} clauses, generics and inlined 7069subprograms. 7070 7071@code{gnatmake} automatically takes care of the third and fourth steps 7072of this process. It determines which sources need to be compiled, 7073compiles them, and binds and links the resulting object files. 7074 7075Unlike some other Ada make programs, the dependencies are always 7076accurately recomputed from the new sources. The source based approach of 7077the GNAT compilation model makes this possible. This means that if 7078changes to the source program cause corresponding changes in 7079dependencies, they will always be tracked exactly correctly by 7080@code{gnatmake}. 7081 7082Note that for advanced forms of project structure, we recommend creating 7083a project file as explained in the @emph{GNAT_Project_Manager} chapter in the 7084@emph{GPRbuild User's Guide}, and using the 7085@code{gprbuild} tool which supports building with project files and works similarly 7086to @code{gnatmake}. 7087 7088@menu 7089* Running gnatmake:: 7090* Switches for gnatmake:: 7091* Mode Switches for gnatmake:: 7092* Notes on the Command Line:: 7093* How gnatmake Works:: 7094* Examples of gnatmake Usage:: 7095 7096@end menu 7097 7098@node Running gnatmake,Switches for gnatmake,,Building with gnatmake 7099@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{cb}@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{cc} 7100@subsection Running @code{gnatmake} 7101 7102 7103The usual form of the @code{gnatmake} command is 7104 7105@example 7106$ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>] 7107@end example 7108 7109The only required argument is one @code{file_name}, which specifies 7110a compilation unit that is a main program. Several @code{file_names} can be 7111specified: this will result in several executables being built. 7112If @code{switches} are present, they can be placed before the first 7113@code{file_name}, between @code{file_names} or after the last @code{file_name}. 7114If @code{mode_switches} are present, they must always be placed after 7115the last @code{file_name} and all @code{switches}. 7116 7117If you are using standard file extensions (@code{.adb} and 7118@code{.ads}), then the 7119extension may be omitted from the @code{file_name} arguments. However, if 7120you are using non-standard extensions, then it is required that the 7121extension be given. A relative or absolute directory path can be 7122specified in a @code{file_name}, in which case, the input source file will 7123be searched for in the specified directory only. Otherwise, the input 7124source file will first be searched in the directory where 7125@code{gnatmake} was invoked and if it is not found, it will be search on 7126the source path of the compiler as described in 7127@ref{73,,Search Paths and the Run-Time Library (RTL)}. 7128 7129All @code{gnatmake} output (except when you specify @code{-M}) is sent to 7130@code{stderr}. The output produced by the 7131@code{-M} switch is sent to @code{stdout}. 7132 7133@node Switches for gnatmake,Mode Switches for gnatmake,Running gnatmake,Building with gnatmake 7134@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{cd}@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{ce} 7135@subsection Switches for @code{gnatmake} 7136 7137 7138You may specify any of the following switches to @code{gnatmake}: 7139 7140@geindex --version (gnatmake) 7141 7142 7143@table @asis 7144 7145@item @code{--version} 7146 7147Display Copyright and version, then exit disregarding all other options. 7148@end table 7149 7150@geindex --help (gnatmake) 7151 7152 7153@table @asis 7154 7155@item @code{--help} 7156 7157If @code{--version} was not used, display usage, then exit disregarding 7158all other options. 7159@end table 7160 7161@geindex --GCC=compiler_name (gnatmake) 7162 7163 7164@table @asis 7165 7166@item @code{--GCC=@emph{compiler_name}} 7167 7168Program used for compiling. The default is @code{gcc}. You need to use 7169quotes around @code{compiler_name} if @code{compiler_name} contains 7170spaces or other separator characters. 7171As an example @code{--GCC="foo -x -y"} 7172will instruct @code{gnatmake} to use @code{foo -x -y} as your 7173compiler. A limitation of this syntax is that the name and path name of 7174the executable itself must not include any embedded spaces. Note that 7175switch @code{-c} is always inserted after your command name. Thus in the 7176above example the compiler command that will be used by @code{gnatmake} 7177will be @code{foo -c -x -y}. If several @code{--GCC=compiler_name} are 7178used, only the last @code{compiler_name} is taken into account. However, 7179all the additional switches are also taken into account. Thus, 7180@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to 7181@code{--GCC="bar -x -y -z -t"}. 7182@end table 7183 7184@geindex --GNATBIND=binder_name (gnatmake) 7185 7186 7187@table @asis 7188 7189@item @code{--GNATBIND=@emph{binder_name}} 7190 7191Program used for binding. The default is @code{gnatbind}. You need to 7192use quotes around @code{binder_name} if @code{binder_name} contains spaces 7193or other separator characters. 7194As an example @code{--GNATBIND="bar -x -y"} 7195will instruct @code{gnatmake} to use @code{bar -x -y} as your 7196binder. Binder switches that are normally appended by @code{gnatmake} 7197to @code{gnatbind} are now appended to the end of @code{bar -x -y}. 7198A limitation of this syntax is that the name and path name of the executable 7199itself must not include any embedded spaces. 7200@end table 7201 7202@geindex --GNATLINK=linker_name (gnatmake) 7203 7204 7205@table @asis 7206 7207@item @code{--GNATLINK=@emph{linker_name}} 7208 7209Program used for linking. The default is @code{gnatlink}. You need to 7210use quotes around @code{linker_name} if @code{linker_name} contains spaces 7211or other separator characters. 7212As an example @code{--GNATLINK="lan -x -y"} 7213will instruct @code{gnatmake} to use @code{lan -x -y} as your 7214linker. Linker switches that are normally appended by @code{gnatmake} to 7215@code{gnatlink} are now appended to the end of @code{lan -x -y}. 7216A limitation of this syntax is that the name and path name of the executable 7217itself must not include any embedded spaces. 7218 7219@item @code{--create-map-file} 7220 7221When linking an executable, create a map file. The name of the map file 7222has the same name as the executable with extension ".map". 7223 7224@item @code{--create-map-file=@emph{mapfile}} 7225 7226When linking an executable, create a map file with the specified name. 7227@end table 7228 7229@geindex --create-missing-dirs (gnatmake) 7230 7231 7232@table @asis 7233 7234@item @code{--create-missing-dirs} 7235 7236When using project files (@code{-P@emph{project}}), automatically create 7237missing object directories, library directories and exec 7238directories. 7239 7240@item @code{--single-compile-per-obj-dir} 7241 7242Disallow simultaneous compilations in the same object directory when 7243project files are used. 7244 7245@item @code{--subdirs=@emph{subdir}} 7246 7247Actual object directory of each project file is the subdirectory subdir of the 7248object directory specified or defaulted in the project file. 7249 7250@item @code{--unchecked-shared-lib-imports} 7251 7252By default, shared library projects are not allowed to import static library 7253projects. When this switch is used on the command line, this restriction is 7254relaxed. 7255 7256@item @code{--source-info=@emph{source info file}} 7257 7258Specify a source info file. This switch is active only when project files 7259are used. If the source info file is specified as a relative path, then it is 7260relative to the object directory of the main project. If the source info file 7261does not exist, then after the Project Manager has successfully parsed and 7262processed the project files and found the sources, it creates the source info 7263file. If the source info file already exists and can be read successfully, 7264then the Project Manager will get all the needed information about the sources 7265from the source info file and will not look for them. This reduces the time 7266to process the project files, especially when looking for sources that take a 7267long time. If the source info file exists but cannot be parsed successfully, 7268the Project Manager will attempt to recreate it. If the Project Manager fails 7269to create the source info file, a message is issued, but gnatmake does not 7270fail. @code{gnatmake} "trusts" the source info file. This means that 7271if the source files have changed (addition, deletion, moving to a different 7272source directory), then the source info file need to be deleted and recreated. 7273@end table 7274 7275@geindex -a (gnatmake) 7276 7277 7278@table @asis 7279 7280@item @code{-a} 7281 7282Consider all files in the make process, even the GNAT internal system 7283files (for example, the predefined Ada library files), as well as any 7284locked files. Locked files are files whose ALI file is write-protected. 7285By default, 7286@code{gnatmake} does not check these files, 7287because the assumption is that the GNAT internal files are properly up 7288to date, and also that any write protected ALI files have been properly 7289installed. Note that if there is an installation problem, such that one 7290of these files is not up to date, it will be properly caught by the 7291binder. 7292You may have to specify this switch if you are working on GNAT 7293itself. The switch @code{-a} is also useful 7294in conjunction with @code{-f} 7295if you need to recompile an entire application, 7296including run-time files, using special configuration pragmas, 7297such as a @code{Normalize_Scalars} pragma. 7298 7299By default 7300@code{gnatmake -a} compiles all GNAT 7301internal files with 7302@code{gcc -c -gnatpg} rather than @code{gcc -c}. 7303@end table 7304 7305@geindex -b (gnatmake) 7306 7307 7308@table @asis 7309 7310@item @code{-b} 7311 7312Bind only. Can be combined with @code{-c} to do 7313compilation and binding, but no link. 7314Can be combined with @code{-l} 7315to do binding and linking. When not combined with 7316@code{-c} 7317all the units in the closure of the main program must have been previously 7318compiled and must be up to date. The root unit specified by @code{file_name} 7319may be given without extension, with the source extension or, if no GNAT 7320Project File is specified, with the ALI file extension. 7321@end table 7322 7323@geindex -c (gnatmake) 7324 7325 7326@table @asis 7327 7328@item @code{-c} 7329 7330Compile only. Do not perform binding, except when @code{-b} 7331is also specified. Do not perform linking, except if both 7332@code{-b} and 7333@code{-l} are also specified. 7334If the root unit specified by @code{file_name} is not a main unit, this is the 7335default. Otherwise @code{gnatmake} will attempt binding and linking 7336unless all objects are up to date and the executable is more recent than 7337the objects. 7338@end table 7339 7340@geindex -C (gnatmake) 7341 7342 7343@table @asis 7344 7345@item @code{-C} 7346 7347Use a temporary mapping file. A mapping file is a way to communicate 7348to the compiler two mappings: from unit names to file names (without 7349any directory information) and from file names to path names (with 7350full directory information). A mapping file can make the compiler's 7351file searches faster, especially if there are many source directories, 7352or the sources are read over a slow network connection. If 7353@code{-P} is used, a mapping file is always used, so 7354@code{-C} is unnecessary; in this case the mapping file 7355is initially populated based on the project file. If 7356@code{-C} is used without 7357@code{-P}, 7358the mapping file is initially empty. Each invocation of the compiler 7359will add any newly accessed sources to the mapping file. 7360@end table 7361 7362@geindex -C= (gnatmake) 7363 7364 7365@table @asis 7366 7367@item @code{-C=@emph{file}} 7368 7369Use a specific mapping file. The file, specified as a path name (absolute or 7370relative) by this switch, should already exist, otherwise the switch is 7371ineffective. The specified mapping file will be communicated to the compiler. 7372This switch is not compatible with a project file 7373(-P`file`) or with multiple compiling processes 7374(-jnnn, when nnn is greater than 1). 7375@end table 7376 7377@geindex -d (gnatmake) 7378 7379 7380@table @asis 7381 7382@item @code{-d} 7383 7384Display progress for each source, up to date or not, as a single line: 7385 7386@example 7387completed x out of y (zz%) 7388@end example 7389 7390If the file needs to be compiled this is displayed after the invocation of 7391the compiler. These lines are displayed even in quiet output mode. 7392@end table 7393 7394@geindex -D (gnatmake) 7395 7396 7397@table @asis 7398 7399@item @code{-D @emph{dir}} 7400 7401Put all object files and ALI file in directory @code{dir}. 7402If the @code{-D} switch is not used, all object files 7403and ALI files go in the current working directory. 7404 7405This switch cannot be used when using a project file. 7406@end table 7407 7408@geindex -eI (gnatmake) 7409 7410 7411@table @asis 7412 7413@item @code{-eI@emph{nnn}} 7414 7415Indicates that the main source is a multi-unit source and the rank of the unit 7416in the source file is nnn. nnn needs to be a positive number and a valid 7417index in the source. This switch cannot be used when @code{gnatmake} is 7418invoked for several mains. 7419@end table 7420 7421@geindex -eL (gnatmake) 7422 7423@geindex symbolic links 7424 7425 7426@table @asis 7427 7428@item @code{-eL} 7429 7430Follow all symbolic links when processing project files. 7431This should be used if your project uses symbolic links for files or 7432directories, but is not needed in other cases. 7433 7434@geindex naming scheme 7435 7436This also assumes that no directory matches the naming scheme for files (for 7437instance that you do not have a directory called "sources.ads" when using the 7438default GNAT naming scheme). 7439 7440When you do not have to use this switch (i.e., by default), gnatmake is able to 7441save a lot of system calls (several per source file and object file), which 7442can result in a significant speed up to load and manipulate a project file, 7443especially when using source files from a remote system. 7444@end table 7445 7446@geindex -eS (gnatmake) 7447 7448 7449@table @asis 7450 7451@item @code{-eS} 7452 7453Output the commands for the compiler, the binder and the linker 7454on standard output, 7455instead of standard error. 7456@end table 7457 7458@geindex -f (gnatmake) 7459 7460 7461@table @asis 7462 7463@item @code{-f} 7464 7465Force recompilations. Recompile all sources, even though some object 7466files may be up to date, but don't recompile predefined or GNAT internal 7467files or locked files (files with a write-protected ALI file), 7468unless the @code{-a} switch is also specified. 7469@end table 7470 7471@geindex -F (gnatmake) 7472 7473 7474@table @asis 7475 7476@item @code{-F} 7477 7478When using project files, if some errors or warnings are detected during 7479parsing and verbose mode is not in effect (no use of switch 7480-v), then error lines start with the full path name of the project 7481file, rather than its simple file name. 7482@end table 7483 7484@geindex -g (gnatmake) 7485 7486 7487@table @asis 7488 7489@item @code{-g} 7490 7491Enable debugging. This switch is simply passed to the compiler and to the 7492linker. 7493@end table 7494 7495@geindex -i (gnatmake) 7496 7497 7498@table @asis 7499 7500@item @code{-i} 7501 7502In normal mode, @code{gnatmake} compiles all object files and ALI files 7503into the current directory. If the @code{-i} switch is used, 7504then instead object files and ALI files that already exist are overwritten 7505in place. This means that once a large project is organized into separate 7506directories in the desired manner, then @code{gnatmake} will automatically 7507maintain and update this organization. If no ALI files are found on the 7508Ada object path (see @ref{73,,Search Paths and the Run-Time Library (RTL)}), 7509the new object and ALI files are created in the 7510directory containing the source being compiled. If another organization 7511is desired, where objects and sources are kept in different directories, 7512a useful technique is to create dummy ALI files in the desired directories. 7513When detecting such a dummy file, @code{gnatmake} will be forced to 7514recompile the corresponding source file, and it will be put the resulting 7515object and ALI files in the directory where it found the dummy file. 7516@end table 7517 7518@geindex -j (gnatmake) 7519 7520@geindex Parallel make 7521 7522 7523@table @asis 7524 7525@item @code{-j@emph{n}} 7526 7527Use @code{n} processes to carry out the (re)compilations. On a multiprocessor 7528machine compilations will occur in parallel. If @code{n} is 0, then the 7529maximum number of parallel compilations is the number of core processors 7530on the platform. In the event of compilation errors, messages from various 7531compilations might get interspersed (but @code{gnatmake} will give you the 7532full ordered list of failing compiles at the end). If this is problematic, 7533rerun the make process with n set to 1 to get a clean list of messages. 7534@end table 7535 7536@geindex -k (gnatmake) 7537 7538 7539@table @asis 7540 7541@item @code{-k} 7542 7543Keep going. Continue as much as possible after a compilation error. To 7544ease the programmer's task in case of compilation errors, the list of 7545sources for which the compile fails is given when @code{gnatmake} 7546terminates. 7547 7548If @code{gnatmake} is invoked with several @code{file_names} and with this 7549switch, if there are compilation errors when building an executable, 7550@code{gnatmake} will not attempt to build the following executables. 7551@end table 7552 7553@geindex -l (gnatmake) 7554 7555 7556@table @asis 7557 7558@item @code{-l} 7559 7560Link only. Can be combined with @code{-b} to binding 7561and linking. Linking will not be performed if combined with 7562@code{-c} 7563but not with @code{-b}. 7564When not combined with @code{-b} 7565all the units in the closure of the main program must have been previously 7566compiled and must be up to date, and the main program needs to have been bound. 7567The root unit specified by @code{file_name} 7568may be given without extension, with the source extension or, if no GNAT 7569Project File is specified, with the ALI file extension. 7570@end table 7571 7572@geindex -m (gnatmake) 7573 7574 7575@table @asis 7576 7577@item @code{-m} 7578 7579Specify that the minimum necessary amount of recompilations 7580be performed. In this mode @code{gnatmake} ignores time 7581stamp differences when the only 7582modifications to a source file consist in adding/removing comments, 7583empty lines, spaces or tabs. This means that if you have changed the 7584comments in a source file or have simply reformatted it, using this 7585switch will tell @code{gnatmake} not to recompile files that depend on it 7586(provided other sources on which these files depend have undergone no 7587semantic modifications). Note that the debugging information may be 7588out of date with respect to the sources if the @code{-m} switch causes 7589a compilation to be switched, so the use of this switch represents a 7590trade-off between compilation time and accurate debugging information. 7591@end table 7592 7593@geindex Dependencies 7594@geindex producing list 7595 7596@geindex -M (gnatmake) 7597 7598 7599@table @asis 7600 7601@item @code{-M} 7602 7603Check if all objects are up to date. If they are, output the object 7604dependences to @code{stdout} in a form that can be directly exploited in 7605a @code{Makefile}. By default, each source file is prefixed with its 7606(relative or absolute) directory name. This name is whatever you 7607specified in the various @code{-aI} 7608and @code{-I} switches. If you use 7609@code{gnatmake -M} @code{-q} 7610(see below), only the source file names, 7611without relative paths, are output. If you just specify the @code{-M} 7612switch, dependencies of the GNAT internal system files are omitted. This 7613is typically what you want. If you also specify 7614the @code{-a} switch, 7615dependencies of the GNAT internal files are also listed. Note that 7616dependencies of the objects in external Ada libraries (see 7617switch @code{-aL@emph{dir}} in the following list) 7618are never reported. 7619@end table 7620 7621@geindex -n (gnatmake) 7622 7623 7624@table @asis 7625 7626@item @code{-n} 7627 7628Don't compile, bind, or link. Checks if all objects are up to date. 7629If they are not, the full name of the first file that needs to be 7630recompiled is printed. 7631Repeated use of this option, followed by compiling the indicated source 7632file, will eventually result in recompiling all required units. 7633@end table 7634 7635@geindex -o (gnatmake) 7636 7637 7638@table @asis 7639 7640@item @code{-o @emph{exec_name}} 7641 7642Output executable name. The name of the final executable program will be 7643@code{exec_name}. If the @code{-o} switch is omitted the default 7644name for the executable will be the name of the input file in appropriate form 7645for an executable file on the host system. 7646 7647This switch cannot be used when invoking @code{gnatmake} with several 7648@code{file_names}. 7649@end table 7650 7651@geindex -p (gnatmake) 7652 7653 7654@table @asis 7655 7656@item @code{-p} 7657 7658Same as @code{--create-missing-dirs} 7659@end table 7660 7661@geindex -P (gnatmake) 7662 7663 7664@table @asis 7665 7666@item @code{-P@emph{project}} 7667 7668Use project file @code{project}. Only one such switch can be used. 7669@end table 7670 7671@c -- Comment: 7672@c :ref:`gnatmake_and_Project_Files`. 7673 7674@geindex -q (gnatmake) 7675 7676 7677@table @asis 7678 7679@item @code{-q} 7680 7681Quiet. When this flag is not set, the commands carried out by 7682@code{gnatmake} are displayed. 7683@end table 7684 7685@geindex -s (gnatmake) 7686 7687 7688@table @asis 7689 7690@item @code{-s} 7691 7692Recompile if compiler switches have changed since last compilation. 7693All compiler switches but -I and -o are taken into account in the 7694following way: 7695orders between different 'first letter' switches are ignored, but 7696orders between same switches are taken into account. For example, 7697@code{-O -O2} is different than @code{-O2 -O}, but @code{-g -O} 7698is equivalent to @code{-O -g}. 7699 7700This switch is recommended when Integrated Preprocessing is used. 7701@end table 7702 7703@geindex -u (gnatmake) 7704 7705 7706@table @asis 7707 7708@item @code{-u} 7709 7710Unique. Recompile at most the main files. It implies -c. Combined with 7711-f, it is equivalent to calling the compiler directly. Note that using 7712-u with a project file and no main has a special meaning. 7713@end table 7714 7715@c --Comment 7716@c (See :ref:`Project_Files_and_Main_Subprograms`.) 7717 7718@geindex -U (gnatmake) 7719 7720 7721@table @asis 7722 7723@item @code{-U} 7724 7725When used without a project file or with one or several mains on the command 7726line, is equivalent to -u. When used with a project file and no main 7727on the command line, all sources of all project files are checked and compiled 7728if not up to date, and libraries are rebuilt, if necessary. 7729@end table 7730 7731@geindex -v (gnatmake) 7732 7733 7734@table @asis 7735 7736@item @code{-v} 7737 7738Verbose. Display the reason for all recompilations @code{gnatmake} 7739decides are necessary, with the highest verbosity level. 7740@end table 7741 7742@geindex -vl (gnatmake) 7743 7744 7745@table @asis 7746 7747@item @code{-vl} 7748 7749Verbosity level Low. Display fewer lines than in verbosity Medium. 7750@end table 7751 7752@geindex -vm (gnatmake) 7753 7754 7755@table @asis 7756 7757@item @code{-vm} 7758 7759Verbosity level Medium. Potentially display fewer lines than in verbosity High. 7760@end table 7761 7762@geindex -vm (gnatmake) 7763 7764 7765@table @asis 7766 7767@item @code{-vh} 7768 7769Verbosity level High. Equivalent to -v. 7770 7771@item @code{-vP@emph{x}} 7772 7773Indicate the verbosity of the parsing of GNAT project files. 7774See @ref{cf,,Switches Related to Project Files}. 7775@end table 7776 7777@geindex -x (gnatmake) 7778 7779 7780@table @asis 7781 7782@item @code{-x} 7783 7784Indicate that sources that are not part of any Project File may be compiled. 7785Normally, when using Project Files, only sources that are part of a Project 7786File may be compile. When this switch is used, a source outside of all Project 7787Files may be compiled. The ALI file and the object file will be put in the 7788object directory of the main Project. The compilation switches used will only 7789be those specified on the command line. Even when 7790@code{-x} is used, mains specified on the 7791command line need to be sources of a project file. 7792 7793@item @code{-X@emph{name}=@emph{value}} 7794 7795Indicate that external variable @code{name} has the value @code{value}. 7796The Project Manager will use this value for occurrences of 7797@code{external(name)} when parsing the project file. 7798@ref{cf,,Switches Related to Project Files}. 7799@end table 7800 7801@geindex -z (gnatmake) 7802 7803 7804@table @asis 7805 7806@item @code{-z} 7807 7808No main subprogram. Bind and link the program even if the unit name 7809given on the command line is a package name. The resulting executable 7810will execute the elaboration routines of the package and its closure, 7811then the finalization routines. 7812@end table 7813 7814@subsubheading GCC switches 7815 7816 7817Any uppercase or multi-character switch that is not a @code{gnatmake} switch 7818is passed to @code{gcc} (e.g., @code{-O}, @code{-gnato,} etc.) 7819 7820@subsubheading Source and library search path switches 7821 7822 7823@geindex -aI (gnatmake) 7824 7825 7826@table @asis 7827 7828@item @code{-aI@emph{dir}} 7829 7830When looking for source files also look in directory @code{dir}. 7831The order in which source files search is undertaken is 7832described in @ref{73,,Search Paths and the Run-Time Library (RTL)}. 7833@end table 7834 7835@geindex -aL (gnatmake) 7836 7837 7838@table @asis 7839 7840@item @code{-aL@emph{dir}} 7841 7842Consider @code{dir} as being an externally provided Ada library. 7843Instructs @code{gnatmake} to skip compilation units whose @code{.ALI} 7844files have been located in directory @code{dir}. This allows you to have 7845missing bodies for the units in @code{dir} and to ignore out of date bodies 7846for the same units. You still need to specify 7847the location of the specs for these units by using the switches 7848@code{-aI@emph{dir}} or @code{-I@emph{dir}}. 7849Note: this switch is provided for compatibility with previous versions 7850of @code{gnatmake}. The easier method of causing standard libraries 7851to be excluded from consideration is to write-protect the corresponding 7852ALI files. 7853@end table 7854 7855@geindex -aO (gnatmake) 7856 7857 7858@table @asis 7859 7860@item @code{-aO@emph{dir}} 7861 7862When searching for library and object files, look in directory 7863@code{dir}. The order in which library files are searched is described in 7864@ref{76,,Search Paths for gnatbind}. 7865@end table 7866 7867@geindex Search paths 7868@geindex for gnatmake 7869 7870@geindex -A (gnatmake) 7871 7872 7873@table @asis 7874 7875@item @code{-A@emph{dir}} 7876 7877Equivalent to @code{-aL@emph{dir}} @code{-aI@emph{dir}}. 7878 7879@geindex -I (gnatmake) 7880 7881@item @code{-I@emph{dir}} 7882 7883Equivalent to @code{-aO@emph{dir} -aI@emph{dir}}. 7884@end table 7885 7886@geindex -I- (gnatmake) 7887 7888@geindex Source files 7889@geindex suppressing search 7890 7891 7892@table @asis 7893 7894@item @code{-I-} 7895 7896Do not look for source files in the directory containing the source 7897file named in the command line. 7898Do not look for ALI or object files in the directory 7899where @code{gnatmake} was invoked. 7900@end table 7901 7902@geindex -L (gnatmake) 7903 7904@geindex Linker libraries 7905 7906 7907@table @asis 7908 7909@item @code{-L@emph{dir}} 7910 7911Add directory @code{dir} to the list of directories in which the linker 7912will search for libraries. This is equivalent to 7913@code{-largs} @code{-L@emph{dir}}. 7914Furthermore, under Windows, the sources pointed to by the libraries path 7915set in the registry are not searched for. 7916@end table 7917 7918@geindex -nostdinc (gnatmake) 7919 7920 7921@table @asis 7922 7923@item @code{-nostdinc} 7924 7925Do not look for source files in the system default directory. 7926@end table 7927 7928@geindex -nostdlib (gnatmake) 7929 7930 7931@table @asis 7932 7933@item @code{-nostdlib} 7934 7935Do not look for library files in the system default directory. 7936@end table 7937 7938@geindex --RTS (gnatmake) 7939 7940 7941@table @asis 7942 7943@item @code{--RTS=@emph{rts-path}} 7944 7945Specifies the default location of the run-time library. GNAT looks for the 7946run-time 7947in the following directories, and stops as soon as a valid run-time is found 7948(@code{adainclude} or @code{ada_source_path}, and @code{adalib} or 7949@code{ada_object_path} present): 7950 7951 7952@itemize * 7953 7954@item 7955@emph{<current directory>/$rts_path} 7956 7957@item 7958@emph{<default-search-dir>/$rts_path} 7959 7960@item 7961@emph{<default-search-dir>/rts-$rts_path} 7962 7963@item 7964The selected path is handled like a normal RTS path. 7965@end itemize 7966@end table 7967 7968@node Mode Switches for gnatmake,Notes on the Command Line,Switches for gnatmake,Building with gnatmake 7969@anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{d0}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{d1} 7970@subsection Mode Switches for @code{gnatmake} 7971 7972 7973The mode switches (referred to as @code{mode_switches}) allow the 7974inclusion of switches that are to be passed to the compiler itself, the 7975binder or the linker. The effect of a mode switch is to cause all 7976subsequent switches up to the end of the switch list, or up to the next 7977mode switch, to be interpreted as switches to be passed on to the 7978designated component of GNAT. 7979 7980@geindex -cargs (gnatmake) 7981 7982 7983@table @asis 7984 7985@item @code{-cargs @emph{switches}} 7986 7987Compiler switches. Here @code{switches} is a list of switches 7988that are valid switches for @code{gcc}. They will be passed on to 7989all compile steps performed by @code{gnatmake}. 7990@end table 7991 7992@geindex -bargs (gnatmake) 7993 7994 7995@table @asis 7996 7997@item @code{-bargs @emph{switches}} 7998 7999Binder switches. Here @code{switches} is a list of switches 8000that are valid switches for @code{gnatbind}. They will be passed on to 8001all bind steps performed by @code{gnatmake}. 8002@end table 8003 8004@geindex -largs (gnatmake) 8005 8006 8007@table @asis 8008 8009@item @code{-largs @emph{switches}} 8010 8011Linker switches. Here @code{switches} is a list of switches 8012that are valid switches for @code{gnatlink}. They will be passed on to 8013all link steps performed by @code{gnatmake}. 8014@end table 8015 8016@geindex -margs (gnatmake) 8017 8018 8019@table @asis 8020 8021@item @code{-margs @emph{switches}} 8022 8023Make switches. The switches are directly interpreted by @code{gnatmake}, 8024regardless of any previous occurrence of @code{-cargs}, @code{-bargs} 8025or @code{-largs}. 8026@end table 8027 8028@node Notes on the Command Line,How gnatmake Works,Mode Switches for gnatmake,Building with gnatmake 8029@anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{d2}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{d3} 8030@subsection Notes on the Command Line 8031 8032 8033This section contains some additional useful notes on the operation 8034of the @code{gnatmake} command. 8035 8036@geindex Recompilation (by gnatmake) 8037 8038 8039@itemize * 8040 8041@item 8042If @code{gnatmake} finds no ALI files, it recompiles the main program 8043and all other units required by the main program. 8044This means that @code{gnatmake} 8045can be used for the initial compile, as well as during subsequent steps of 8046the development cycle. 8047 8048@item 8049If you enter @code{gnatmake foo.adb}, where @code{foo} 8050is a subunit or body of a generic unit, @code{gnatmake} recompiles 8051@code{foo.adb} (because it finds no ALI) and stops, issuing a 8052warning. 8053 8054@item 8055In @code{gnatmake} the switch @code{-I} 8056is used to specify both source and 8057library file paths. Use @code{-aI} 8058instead if you just want to specify 8059source paths only and @code{-aO} 8060if you want to specify library paths 8061only. 8062 8063@item 8064@code{gnatmake} will ignore any files whose ALI file is write-protected. 8065This may conveniently be used to exclude standard libraries from 8066consideration and in particular it means that the use of the 8067@code{-f} switch will not recompile these files 8068unless @code{-a} is also specified. 8069 8070@item 8071@code{gnatmake} has been designed to make the use of Ada libraries 8072particularly convenient. Assume you have an Ada library organized 8073as follows: @emph{obj-dir} contains the objects and ALI files for 8074of your Ada compilation units, 8075whereas @emph{include-dir} contains the 8076specs of these units, but no bodies. Then to compile a unit 8077stored in @code{main.adb}, which uses this Ada library you would just type: 8078 8079@example 8080$ gnatmake -aI`include-dir` -aL`obj-dir` main 8081@end example 8082 8083@item 8084Using @code{gnatmake} along with the @code{-m (minimal recompilation)} 8085switch provides a mechanism for avoiding unnecessary recompilations. Using 8086this switch, 8087you can update the comments/format of your 8088source files without having to recompile everything. Note, however, that 8089adding or deleting lines in a source files may render its debugging 8090info obsolete. If the file in question is a spec, the impact is rather 8091limited, as that debugging info will only be useful during the 8092elaboration phase of your program. For bodies the impact can be more 8093significant. In all events, your debugger will warn you if a source file 8094is more recent than the corresponding object, and alert you to the fact 8095that the debugging information may be out of date. 8096@end itemize 8097 8098@node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake 8099@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{d4}@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{d5} 8100@subsection How @code{gnatmake} Works 8101 8102 8103Generally @code{gnatmake} automatically performs all necessary 8104recompilations and you don't need to worry about how it works. However, 8105it may be useful to have some basic understanding of the @code{gnatmake} 8106approach and in particular to understand how it uses the results of 8107previous compilations without incorrectly depending on them. 8108 8109First a definition: an object file is considered @emph{up to date} if the 8110corresponding ALI file exists and if all the source files listed in the 8111dependency section of this ALI file have time stamps matching those in 8112the ALI file. This means that neither the source file itself nor any 8113files that it depends on have been modified, and hence there is no need 8114to recompile this file. 8115 8116@code{gnatmake} works by first checking if the specified main unit is up 8117to date. If so, no compilations are required for the main unit. If not, 8118@code{gnatmake} compiles the main program to build a new ALI file that 8119reflects the latest sources. Then the ALI file of the main unit is 8120examined to find all the source files on which the main program depends, 8121and @code{gnatmake} recursively applies the above procedure on all these 8122files. 8123 8124This process ensures that @code{gnatmake} only trusts the dependencies 8125in an existing ALI file if they are known to be correct. Otherwise it 8126always recompiles to determine a new, guaranteed accurate set of 8127dependencies. As a result the program is compiled 'upside down' from what may 8128be more familiar as the required order of compilation in some other Ada 8129systems. In particular, clients are compiled before the units on which 8130they depend. The ability of GNAT to compile in any order is critical in 8131allowing an order of compilation to be chosen that guarantees that 8132@code{gnatmake} will recompute a correct set of new dependencies if 8133necessary. 8134 8135When invoking @code{gnatmake} with several @code{file_names}, if a unit is 8136imported by several of the executables, it will be recompiled at most once. 8137 8138Note: when using non-standard naming conventions 8139(@ref{1c,,Using Other File Names}), changing through a configuration pragmas 8140file the version of a source and invoking @code{gnatmake} to recompile may 8141have no effect, if the previous version of the source is still accessible 8142by @code{gnatmake}. It may be necessary to use the switch 8143-f. 8144 8145@node Examples of gnatmake Usage,,How gnatmake Works,Building with gnatmake 8146@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{d6}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{d7} 8147@subsection Examples of @code{gnatmake} Usage 8148 8149 8150 8151@table @asis 8152 8153@item @emph{gnatmake hello.adb} 8154 8155Compile all files necessary to bind and link the main program 8156@code{hello.adb} (containing unit @code{Hello}) and bind and link the 8157resulting object files to generate an executable file @code{hello}. 8158 8159@item @emph{gnatmake main1 main2 main3} 8160 8161Compile all files necessary to bind and link the main programs 8162@code{main1.adb} (containing unit @code{Main1}), @code{main2.adb} 8163(containing unit @code{Main2}) and @code{main3.adb} 8164(containing unit @code{Main3}) and bind and link the resulting object files 8165to generate three executable files @code{main1}, 8166@code{main2} and @code{main3}. 8167 8168@item @emph{gnatmake -q Main_Unit -cargs -O2 -bargs -l} 8169 8170Compile all files necessary to bind and link the main program unit 8171@code{Main_Unit} (from file @code{main_unit.adb}). All compilations will 8172be done with optimization level 2 and the order of elaboration will be 8173listed by the binder. @code{gnatmake} will operate in quiet mode, not 8174displaying commands it is executing. 8175@end table 8176 8177@node Compiling with gcc,Compiler Switches,Building with gnatmake,Building Executable Programs with GNAT 8178@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{c7}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{d8} 8179@section Compiling with @code{gcc} 8180 8181 8182This section discusses how to compile Ada programs using the @code{gcc} 8183command. It also describes the set of switches 8184that can be used to control the behavior of the compiler. 8185 8186@menu 8187* Compiling Programs:: 8188* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. 8189* Order of Compilation Issues:: 8190* Examples:: 8191 8192@end menu 8193 8194@node Compiling Programs,Search Paths and the Run-Time Library RTL,,Compiling with gcc 8195@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{d9}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{da} 8196@subsection Compiling Programs 8197 8198 8199The first step in creating an executable program is to compile the units 8200of the program using the @code{gcc} command. You must compile the 8201following files: 8202 8203 8204@itemize * 8205 8206@item 8207the body file (@code{.adb}) for a library level subprogram or generic 8208subprogram 8209 8210@item 8211the spec file (@code{.ads}) for a library level package or generic 8212package that has no body 8213 8214@item 8215the body file (@code{.adb}) for a library level package 8216or generic package that has a body 8217@end itemize 8218 8219You need @emph{not} compile the following files 8220 8221 8222@itemize * 8223 8224@item 8225the spec of a library unit which has a body 8226 8227@item 8228subunits 8229@end itemize 8230 8231because they are compiled as part of compiling related units. GNAT 8232package specs 8233when the corresponding body is compiled, and subunits when the parent is 8234compiled. 8235 8236@geindex cannot generate code 8237 8238If you attempt to compile any of these files, you will get one of the 8239following error messages (where @code{fff} is the name of the file you 8240compiled): 8241 8242@quotation 8243 8244@example 8245cannot generate code for file `@w{`}fff`@w{`} (package spec) 8246to check package spec, use -gnatc 8247 8248cannot generate code for file `@w{`}fff`@w{`} (missing subunits) 8249to check parent unit, use -gnatc 8250 8251cannot generate code for file `@w{`}fff`@w{`} (subprogram spec) 8252to check subprogram spec, use -gnatc 8253 8254cannot generate code for file `@w{`}fff`@w{`} (subunit) 8255to check subunit, use -gnatc 8256@end example 8257@end quotation 8258 8259As indicated by the above error messages, if you want to submit 8260one of these files to the compiler to check for correct semantics 8261without generating code, then use the @code{-gnatc} switch. 8262 8263The basic command for compiling a file containing an Ada unit is: 8264 8265@example 8266$ gcc -c [switches] <file name> 8267@end example 8268 8269where @code{file name} is the name of the Ada file (usually 8270having an extension @code{.ads} for a spec or @code{.adb} for a body). 8271You specify the 8272@code{-c} switch to tell @code{gcc} to compile, but not link, the file. 8273The result of a successful compilation is an object file, which has the 8274same name as the source file but an extension of @code{.o} and an Ada 8275Library Information (ALI) file, which also has the same name as the 8276source file, but with @code{.ali} as the extension. GNAT creates these 8277two output files in the current directory, but you may specify a source 8278file in any directory using an absolute or relative path specification 8279containing the directory information. 8280 8281TESTING: the @code{--foobar@emph{NN}} switch 8282 8283@geindex gnat1 8284 8285@code{gcc} is actually a driver program that looks at the extensions of 8286the file arguments and loads the appropriate compiler. For example, the 8287GNU C compiler is @code{cc1}, and the Ada compiler is @code{gnat1}. 8288These programs are in directories known to the driver program (in some 8289configurations via environment variables you set), but need not be in 8290your path. The @code{gcc} driver also calls the assembler and any other 8291utilities needed to complete the generation of the required object 8292files. 8293 8294It is possible to supply several file names on the same @code{gcc} 8295command. This causes @code{gcc} to call the appropriate compiler for 8296each file. For example, the following command lists two separate 8297files to be compiled: 8298 8299@example 8300$ gcc -c x.adb y.adb 8301@end example 8302 8303calls @code{gnat1} (the Ada compiler) twice to compile @code{x.adb} and 8304@code{y.adb}. 8305The compiler generates two object files @code{x.o} and @code{y.o} 8306and the two ALI files @code{x.ali} and @code{y.ali}. 8307 8308Any switches apply to all the files listed, see @ref{db,,Compiler Switches} for a 8309list of available @code{gcc} switches. 8310 8311@node Search Paths and the Run-Time Library RTL,Order of Compilation Issues,Compiling Programs,Compiling with gcc 8312@anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{73} 8313@subsection Search Paths and the Run-Time Library (RTL) 8314 8315 8316With the GNAT source-based library system, the compiler must be able to 8317find source files for units that are needed by the unit being compiled. 8318Search paths are used to guide this process. 8319 8320The compiler compiles one source file whose name must be given 8321explicitly on the command line. In other words, no searching is done 8322for this file. To find all other source files that are needed (the most 8323common being the specs of units), the compiler examines the following 8324directories, in the following order: 8325 8326 8327@itemize * 8328 8329@item 8330The directory containing the source file of the main unit being compiled 8331(the file name on the command line). 8332 8333@item 8334Each directory named by an @code{-I} switch given on the @code{gcc} 8335command line, in the order given. 8336 8337@geindex ADA_PRJ_INCLUDE_FILE 8338 8339@item 8340Each of the directories listed in the text file whose name is given 8341by the 8342@geindex ADA_PRJ_INCLUDE_FILE 8343@geindex environment variable; ADA_PRJ_INCLUDE_FILE 8344@code{ADA_PRJ_INCLUDE_FILE} environment variable. 8345@geindex ADA_PRJ_INCLUDE_FILE 8346@geindex environment variable; ADA_PRJ_INCLUDE_FILE 8347@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the gnat 8348driver when project files are used. It should not normally be set 8349by other means. 8350 8351@geindex ADA_INCLUDE_PATH 8352 8353@item 8354Each of the directories listed in the value of the 8355@geindex ADA_INCLUDE_PATH 8356@geindex environment variable; ADA_INCLUDE_PATH 8357@code{ADA_INCLUDE_PATH} environment variable. 8358Construct this value 8359exactly as the 8360@geindex PATH 8361@geindex environment variable; PATH 8362@code{PATH} environment variable: a list of directory 8363names separated by colons (semicolons when working with the NT version). 8364 8365@item 8366The content of the @code{ada_source_path} file which is part of the GNAT 8367installation tree and is used to store standard libraries such as the 8368GNAT Run Time Library (RTL) source files. 8369@ref{71,,Installing a library} 8370@end itemize 8371 8372Specifying the switch @code{-I-} 8373inhibits the use of the directory 8374containing the source file named in the command line. You can still 8375have this directory on your search path, but in this case it must be 8376explicitly requested with a @code{-I} switch. 8377 8378Specifying the switch @code{-nostdinc} 8379inhibits the search of the default location for the GNAT Run Time 8380Library (RTL) source files. 8381 8382The compiler outputs its object files and ALI files in the current 8383working directory. 8384Caution: The object file can be redirected with the @code{-o} switch; 8385however, @code{gcc} and @code{gnat1} have not been coordinated on this 8386so the @code{ALI} file will not go to the right place. Therefore, you should 8387avoid using the @code{-o} switch. 8388 8389@geindex System.IO 8390 8391The packages @code{Ada}, @code{System}, and @code{Interfaces} and their 8392children make up the GNAT RTL, together with the simple @code{System.IO} 8393package used in the @code{"Hello World"} example. The sources for these units 8394are needed by the compiler and are kept together in one directory. Not 8395all of the bodies are needed, but all of the sources are kept together 8396anyway. In a normal installation, you need not specify these directory 8397names when compiling or binding. Either the environment variables or 8398the built-in defaults cause these files to be found. 8399 8400In addition to the language-defined hierarchies (@code{System}, @code{Ada} and 8401@code{Interfaces}), the GNAT distribution provides a fourth hierarchy, 8402consisting of child units of @code{GNAT}. This is a collection of generally 8403useful types, subprograms, etc. See the @cite{GNAT_Reference_Manual} 8404for further details. 8405 8406Besides simplifying access to the RTL, a major use of search paths is 8407in compiling sources from multiple directories. This can make 8408development environments much more flexible. 8409 8410@node Order of Compilation Issues,Examples,Search Paths and the Run-Time Library RTL,Compiling with gcc 8411@anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{de} 8412@subsection Order of Compilation Issues 8413 8414 8415If, in our earlier example, there was a spec for the @code{hello} 8416procedure, it would be contained in the file @code{hello.ads}; yet this 8417file would not have to be explicitly compiled. This is the result of the 8418model we chose to implement library management. Some of the consequences 8419of this model are as follows: 8420 8421 8422@itemize * 8423 8424@item 8425There is no point in compiling specs (except for package 8426specs with no bodies) because these are compiled as needed by clients. If 8427you attempt a useless compilation, you will receive an error message. 8428It is also useless to compile subunits because they are compiled as needed 8429by the parent. 8430 8431@item 8432There are no order of compilation requirements: performing a 8433compilation never obsoletes anything. The only way you can obsolete 8434something and require recompilations is to modify one of the 8435source files on which it depends. 8436 8437@item 8438There is no library as such, apart from the ALI files 8439(@ref{28,,The Ada Library Information Files}, for information on the format 8440of these files). For now we find it convenient to create separate ALI files, 8441but eventually the information therein may be incorporated into the object 8442file directly. 8443 8444@item 8445When you compile a unit, the source files for the specs of all units 8446that it @emph{with}s, all its subunits, and the bodies of any generics it 8447instantiates must be available (reachable by the search-paths mechanism 8448described above), or you will receive a fatal error message. 8449@end itemize 8450 8451@node Examples,,Order of Compilation Issues,Compiling with gcc 8452@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{e0} 8453@subsection Examples 8454 8455 8456The following are some typical Ada compilation command line examples: 8457 8458@example 8459$ gcc -c xyz.adb 8460@end example 8461 8462Compile body in file @code{xyz.adb} with all default options. 8463 8464@example 8465$ gcc -c -O2 -gnata xyz-def.adb 8466@end example 8467 8468Compile the child unit package in file @code{xyz-def.adb} with extensive 8469optimizations, and pragma @code{Assert}/@cite{Debug} statements 8470enabled. 8471 8472@example 8473$ gcc -c -gnatc abc-def.adb 8474@end example 8475 8476Compile the subunit in file @code{abc-def.adb} in semantic-checking-only 8477mode. 8478 8479@node Compiler Switches,Linker Switches,Compiling with gcc,Building Executable Programs with GNAT 8480@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{e1}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{db} 8481@section Compiler Switches 8482 8483 8484The @code{gcc} command accepts switches that control the 8485compilation process. These switches are fully described in this section: 8486first an alphabetical listing of all switches with a brief description, 8487and then functionally grouped sets of switches with more detailed 8488information. 8489 8490More switches exist for GCC than those documented here, especially 8491for specific targets. However, their use is not recommended as 8492they may change code generation in ways that are incompatible with 8493the Ada run-time library, or can cause inconsistencies between 8494compilation units. 8495 8496@menu 8497* Alphabetical List of All Switches:: 8498* Output and Error Message Control:: 8499* Warning Message Control:: 8500* Debugging and Assertion Control:: 8501* Validity Checking:: 8502* Style Checking:: 8503* Run-Time Checks:: 8504* Using gcc for Syntax Checking:: 8505* Using gcc for Semantic Checking:: 8506* Compiling Different Versions of Ada:: 8507* Character Set Control:: 8508* File Naming Control:: 8509* Subprogram Inlining Control:: 8510* Auxiliary Output Control:: 8511* Debugging Control:: 8512* Exception Handling Control:: 8513* Units to Sources Mapping Files:: 8514* Code Generation Control:: 8515 8516@end menu 8517 8518@node Alphabetical List of All Switches,Output and Error Message Control,,Compiler Switches 8519@anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{e2}@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{e3} 8520@subsection Alphabetical List of All Switches 8521 8522 8523@geindex -b (gcc) 8524 8525 8526@table @asis 8527 8528@item @code{-b @emph{target}} 8529 8530Compile your program to run on @code{target}, which is the name of a 8531system configuration. You must have a GNAT cross-compiler built if 8532@code{target} is not the same as your host system. 8533@end table 8534 8535@geindex -B (gcc) 8536 8537 8538@table @asis 8539 8540@item @code{-B@emph{dir}} 8541 8542Load compiler executables (for example, @code{gnat1}, the Ada compiler) 8543from @code{dir} instead of the default location. Only use this switch 8544when multiple versions of the GNAT compiler are available. 8545See the "Options for Directory Search" section in the 8546@cite{Using the GNU Compiler Collection (GCC)} manual for further details. 8547You would normally use the @code{-b} or @code{-V} switch instead. 8548@end table 8549 8550@geindex -c (gcc) 8551 8552 8553@table @asis 8554 8555@item @code{-c} 8556 8557Compile. Always use this switch when compiling Ada programs. 8558 8559Note: for some other languages when using @code{gcc}, notably in 8560the case of C and C++, it is possible to use 8561use @code{gcc} without a @code{-c} switch to 8562compile and link in one step. In the case of GNAT, you 8563cannot use this approach, because the binder must be run 8564and @code{gcc} cannot be used to run the GNAT binder. 8565@end table 8566 8567@geindex -fcallgraph-info (gcc) 8568 8569 8570@table @asis 8571 8572@item @code{-fcallgraph-info[=su,da]} 8573 8574Makes the compiler output callgraph information for the program, on a 8575per-file basis. The information is generated in the VCG format. It can 8576be decorated with additional, per-node and/or per-edge information, if a 8577list of comma-separated markers is additionally specified. When the 8578@code{su} marker is specified, the callgraph is decorated with stack usage 8579information; it is equivalent to @code{-fstack-usage}. When the @code{da} 8580marker is specified, the callgraph is decorated with information about 8581dynamically allocated objects. 8582@end table 8583 8584@geindex -fdump-scos (gcc) 8585 8586 8587@table @asis 8588 8589@item @code{-fdump-scos} 8590 8591Generates SCO (Source Coverage Obligation) information in the ALI file. 8592This information is used by advanced coverage tools. See unit @code{SCOs} 8593in the compiler sources for details in files @code{scos.ads} and 8594@code{scos.adb}. 8595@end table 8596 8597@geindex -fgnat-encodings (gcc) 8598 8599 8600@table @asis 8601 8602@item @code{-fgnat-encodings=[all|gdb|minimal]} 8603 8604This switch controls the balance between GNAT encodings and standard DWARF 8605emitted in the debug information. 8606@end table 8607 8608@geindex -flto (gcc) 8609 8610 8611@table @asis 8612 8613@item @code{-flto[=@emph{n}]} 8614 8615Enables Link Time Optimization. This switch must be used in conjunction 8616with the @code{-Ox} switches (but not with the @code{-gnatn} switch 8617since it is a full replacement for the latter) and instructs the compiler 8618to defer most optimizations until the link stage. The advantage of this 8619approach is that the compiler can do a whole-program analysis and choose 8620the best interprocedural optimization strategy based on a complete view 8621of the program, instead of a fragmentary view with the usual approach. 8622This can also speed up the compilation of big programs and reduce the 8623size of the executable, compared with a traditional per-unit compilation 8624with inlining across units enabled by the @code{-gnatn} switch. 8625The drawback of this approach is that it may require more memory and that 8626the debugging information generated by -g with it might be hardly usable. 8627The switch, as well as the accompanying @code{-Ox} switches, must be 8628specified both for the compilation and the link phases. 8629If the @code{n} parameter is specified, the optimization and final code 8630generation at link time are executed using @code{n} parallel jobs by 8631means of an installed @code{make} program. 8632@end table 8633 8634@geindex -fno-inline (gcc) 8635 8636 8637@table @asis 8638 8639@item @code{-fno-inline} 8640 8641Suppresses all inlining, unless requested with pragma @code{Inline_Always}. The 8642effect is enforced regardless of other optimization or inlining switches. 8643Note that inlining can also be suppressed on a finer-grained basis with 8644pragma @code{No_Inline}. 8645@end table 8646 8647@geindex -fno-inline-functions (gcc) 8648 8649 8650@table @asis 8651 8652@item @code{-fno-inline-functions} 8653 8654Suppresses automatic inlining of subprograms, which is enabled 8655if @code{-O3} is used. 8656@end table 8657 8658@geindex -fno-inline-small-functions (gcc) 8659 8660 8661@table @asis 8662 8663@item @code{-fno-inline-small-functions} 8664 8665Suppresses automatic inlining of small subprograms, which is enabled 8666if @code{-O2} is used. 8667@end table 8668 8669@geindex -fno-inline-functions-called-once (gcc) 8670 8671 8672@table @asis 8673 8674@item @code{-fno-inline-functions-called-once} 8675 8676Suppresses inlining of subprograms local to the unit and called once 8677from within it, which is enabled if @code{-O1} is used. 8678@end table 8679 8680@geindex -fno-ivopts (gcc) 8681 8682 8683@table @asis 8684 8685@item @code{-fno-ivopts} 8686 8687Suppresses high-level loop induction variable optimizations, which are 8688enabled if @code{-O1} is used. These optimizations are generally 8689profitable but, for some specific cases of loops with numerous uses 8690of the iteration variable that follow a common pattern, they may end 8691up destroying the regularity that could be exploited at a lower level 8692and thus producing inferior code. 8693@end table 8694 8695@geindex -fno-strict-aliasing (gcc) 8696 8697 8698@table @asis 8699 8700@item @code{-fno-strict-aliasing} 8701 8702Causes the compiler to avoid assumptions regarding non-aliasing 8703of objects of different types. See 8704@ref{e4,,Optimization and Strict Aliasing} for details. 8705@end table 8706 8707@geindex -fno-strict-overflow (gcc) 8708 8709 8710@table @asis 8711 8712@item @code{-fno-strict-overflow} 8713 8714Causes the compiler to avoid assumptions regarding the rules of signed 8715integer overflow. These rules specify that signed integer overflow will 8716result in a Constraint_Error exception at run time and are enforced in 8717default mode by the compiler, so this switch should not be necessary in 8718normal operating mode. It might be useful in conjunction with @code{-gnato0} 8719for very peculiar cases of low-level programming. 8720@end table 8721 8722@geindex -fstack-check (gcc) 8723 8724 8725@table @asis 8726 8727@item @code{-fstack-check} 8728 8729Activates stack checking. 8730See @ref{e5,,Stack Overflow Checking} for details. 8731@end table 8732 8733@geindex -fstack-usage (gcc) 8734 8735 8736@table @asis 8737 8738@item @code{-fstack-usage} 8739 8740Makes the compiler output stack usage information for the program, on a 8741per-subprogram basis. See @ref{e6,,Static Stack Usage Analysis} for details. 8742@end table 8743 8744@geindex -g (gcc) 8745 8746 8747@table @asis 8748 8749@item @code{-g} 8750 8751Generate debugging information. This information is stored in the object 8752file and copied from there to the final executable file by the linker, 8753where it can be read by the debugger. You must use the 8754@code{-g} switch if you plan on using the debugger. 8755@end table 8756 8757@geindex -gnat05 (gcc) 8758 8759 8760@table @asis 8761 8762@item @code{-gnat05} 8763 8764Allow full Ada 2005 features. 8765@end table 8766 8767@geindex -gnat12 (gcc) 8768 8769 8770@table @asis 8771 8772@item @code{-gnat12} 8773 8774Allow full Ada 2012 features. 8775@end table 8776 8777@geindex -gnat83 (gcc) 8778 8779@geindex -gnat2005 (gcc) 8780 8781 8782@table @asis 8783 8784@item @code{-gnat2005} 8785 8786Allow full Ada 2005 features (same as @code{-gnat05}) 8787@end table 8788 8789@geindex -gnat2012 (gcc) 8790 8791 8792@table @asis 8793 8794@item @code{-gnat2012} 8795 8796Allow full Ada 2012 features (same as @code{-gnat12}) 8797 8798@item @code{-gnat83} 8799 8800Enforce Ada 83 restrictions. 8801@end table 8802 8803@geindex -gnat95 (gcc) 8804 8805 8806@table @asis 8807 8808@item @code{-gnat95} 8809 8810Enforce Ada 95 restrictions. 8811 8812Note: for compatibility with some Ada 95 compilers which support only 8813the @code{overriding} keyword of Ada 2005, the @code{-gnatd.D} switch can 8814be used along with @code{-gnat95} to achieve a similar effect with GNAT. 8815 8816@code{-gnatd.D} instructs GNAT to consider @code{overriding} as a keyword 8817and handle its associated semantic checks, even in Ada 95 mode. 8818@end table 8819 8820@geindex -gnata (gcc) 8821 8822 8823@table @asis 8824 8825@item @code{-gnata} 8826 8827Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be 8828activated. Note that these pragmas can also be controlled using the 8829configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}. 8830It also activates pragmas @code{Check}, @code{Precondition}, and 8831@code{Postcondition}. Note that these pragmas can also be controlled 8832using the configuration pragma @code{Check_Policy}. In Ada 2012, it 8833also activates all assertions defined in the RM as aspects: preconditions, 8834postconditions, type invariants and (sub)type predicates. In all Ada modes, 8835corresponding pragmas for type invariants and (sub)type predicates are 8836also activated. The default is that all these assertions are disabled, 8837and have no effect, other than being checked for syntactic validity, and 8838in the case of subtype predicates, constructions such as membership tests 8839still test predicates even if assertions are turned off. 8840@end table 8841 8842@geindex -gnatA (gcc) 8843 8844 8845@table @asis 8846 8847@item @code{-gnatA} 8848 8849Avoid processing @code{gnat.adc}. If a @code{gnat.adc} file is present, 8850it will be ignored. 8851@end table 8852 8853@geindex -gnatb (gcc) 8854 8855 8856@table @asis 8857 8858@item @code{-gnatb} 8859 8860Generate brief messages to @code{stderr} even if verbose mode set. 8861@end table 8862 8863@geindex -gnatB (gcc) 8864 8865 8866@table @asis 8867 8868@item @code{-gnatB} 8869 8870Assume no invalid (bad) values except for 'Valid attribute use 8871(@ref{e7,,Validity Checking}). 8872@end table 8873 8874@geindex -gnatc (gcc) 8875 8876 8877@table @asis 8878 8879@item @code{-gnatc} 8880 8881Check syntax and semantics only (no code generation attempted). When the 8882compiler is invoked by @code{gnatmake}, if the switch @code{-gnatc} is 8883only given to the compiler (after @code{-cargs} or in package Compiler of 8884the project file, @code{gnatmake} will fail because it will not find the 8885object file after compilation. If @code{gnatmake} is called with 8886@code{-gnatc} as a builder switch (before @code{-cargs} or in package 8887Builder of the project file) then @code{gnatmake} will not fail because 8888it will not look for the object files after compilation, and it will not try 8889to build and link. 8890@end table 8891 8892@geindex -gnatC (gcc) 8893 8894 8895@table @asis 8896 8897@item @code{-gnatC} 8898 8899Generate CodePeer intermediate format (no code generation attempted). 8900This switch will generate an intermediate representation suitable for 8901use by CodePeer (@code{.scil} files). This switch is not compatible with 8902code generation (it will, among other things, disable some switches such 8903as -gnatn, and enable others such as -gnata). 8904@end table 8905 8906@geindex -gnatd (gcc) 8907 8908 8909@table @asis 8910 8911@item @code{-gnatd} 8912 8913Specify debug options for the compiler. The string of characters after 8914the @code{-gnatd} specify the specific debug options. The possible 8915characters are 0-9, a-z, A-Z, optionally preceded by a dot. See 8916compiler source file @code{debug.adb} for details of the implemented 8917debug options. Certain debug options are relevant to applications 8918programmers, and these are documented at appropriate points in this 8919users guide. 8920@end table 8921 8922@geindex -gnatD[nn] (gcc) 8923 8924 8925@table @asis 8926 8927@item @code{-gnatD} 8928 8929Create expanded source files for source level debugging. This switch 8930also suppresses generation of cross-reference information 8931(see @code{-gnatx}). Note that this switch is not allowed if a previous 8932-gnatR switch has been given, since these two switches are not compatible. 8933@end table 8934 8935@geindex -gnateA (gcc) 8936 8937 8938@table @asis 8939 8940@item @code{-gnateA} 8941 8942Check that the actual parameters of a subprogram call are not aliases of one 8943another. To qualify as aliasing, the actuals must denote objects of a composite 8944type, their memory locations must be identical or overlapping, and at least one 8945of the corresponding formal parameters must be of mode OUT or IN OUT. 8946 8947@example 8948type Rec_Typ is record 8949 Data : Integer := 0; 8950end record; 8951 8952function Self (Val : Rec_Typ) return Rec_Typ is 8953begin 8954 return Val; 8955end Self; 8956 8957procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is 8958begin 8959 null; 8960end Detect_Aliasing; 8961 8962Obj : Rec_Typ; 8963 8964Detect_Aliasing (Obj, Obj); 8965Detect_Aliasing (Obj, Self (Obj)); 8966@end example 8967 8968In the example above, the first call to @code{Detect_Aliasing} fails with a 8969@code{Program_Error} at run time because the actuals for @code{Val_1} and 8970@code{Val_2} denote the same object. The second call executes without raising 8971an exception because @code{Self(Obj)} produces an anonymous object which does 8972not share the memory location of @code{Obj}. 8973@end table 8974 8975@geindex -gnateb (gcc) 8976 8977 8978@table @asis 8979 8980@item @code{-gnateb} 8981 8982Store configuration files by their basename in ALI files. This switch is 8983used for instance by gprbuild for distributed builds in order to prevent 8984issues where machine-specific absolute paths could end up being stored in 8985ALI files. 8986@end table 8987 8988@geindex -gnatec (gcc) 8989 8990 8991@table @asis 8992 8993@item @code{-gnatec=@emph{path}} 8994 8995Specify a configuration pragma file 8996(the equal sign is optional) 8997(@ref{62,,The Configuration Pragmas Files}). 8998@end table 8999 9000@geindex -gnateC (gcc) 9001 9002 9003@table @asis 9004 9005@item @code{-gnateC} 9006 9007Generate CodePeer messages in a compiler-like format. This switch is only 9008effective if @code{-gnatcC} is also specified and requires an installation 9009of CodePeer. 9010@end table 9011 9012@geindex -gnated (gcc) 9013 9014 9015@table @asis 9016 9017@item @code{-gnated} 9018 9019Disable atomic synchronization 9020@end table 9021 9022@geindex -gnateD (gcc) 9023 9024 9025@table @asis 9026 9027@item @code{-gnateDsymbol[=@emph{value}]} 9028 9029Defines a symbol, associated with @code{value}, for preprocessing. 9030(@ref{90,,Integrated Preprocessing}). 9031@end table 9032 9033@geindex -gnateE (gcc) 9034 9035 9036@table @asis 9037 9038@item @code{-gnateE} 9039 9040Generate extra information in exception messages. In particular, display 9041extra column information and the value and range associated with index and 9042range check failures, and extra column information for access checks. 9043In cases where the compiler is able to determine at compile time that 9044a check will fail, it gives a warning, and the extra information is not 9045produced at run time. 9046@end table 9047 9048@geindex -gnatef (gcc) 9049 9050 9051@table @asis 9052 9053@item @code{-gnatef} 9054 9055Display full source path name in brief error messages. 9056@end table 9057 9058@geindex -gnateF (gcc) 9059 9060 9061@table @asis 9062 9063@item @code{-gnateF} 9064 9065Check for overflow on all floating-point operations, including those 9066for unconstrained predefined types. See description of pragma 9067@code{Check_Float_Overflow} in GNAT RM. 9068@end table 9069 9070@geindex -gnateg (gcc) 9071 9072@code{-gnateg} 9073@code{-gnatceg} 9074 9075@quotation 9076 9077The @code{-gnatc} switch must always be specified before this switch, e.g. 9078@code{-gnatceg}. Generate a C header from the Ada input file. See 9079@ref{b7,,Generating C Headers for Ada Specifications} for more 9080information. 9081@end quotation 9082 9083@geindex -gnateG (gcc) 9084 9085 9086@table @asis 9087 9088@item @code{-gnateG} 9089 9090Save result of preprocessing in a text file. 9091@end table 9092 9093@geindex -gnatei (gcc) 9094 9095 9096@table @asis 9097 9098@item @code{-gnatei@emph{nnn}} 9099 9100Set maximum number of instantiations during compilation of a single unit to 9101@code{nnn}. This may be useful in increasing the default maximum of 8000 for 9102the rare case when a single unit legitimately exceeds this limit. 9103@end table 9104 9105@geindex -gnateI (gcc) 9106 9107 9108@table @asis 9109 9110@item @code{-gnateI@emph{nnn}} 9111 9112Indicates that the source is a multi-unit source and that the index of the 9113unit to compile is @code{nnn}. @code{nnn} needs to be a positive number and need 9114to be a valid index in the multi-unit source. 9115@end table 9116 9117@geindex -gnatel (gcc) 9118 9119 9120@table @asis 9121 9122@item @code{-gnatel} 9123 9124This switch can be used with the static elaboration model to issue info 9125messages showing 9126where implicit @code{pragma Elaborate} and @code{pragma Elaborate_All} 9127are generated. This is useful in diagnosing elaboration circularities 9128caused by these implicit pragmas when using the static elaboration 9129model. See See the section in this guide on elaboration checking for 9130further details. These messages are not generated by default, and are 9131intended only for temporary use when debugging circularity problems. 9132@end table 9133 9134@geindex -gnatel (gcc) 9135 9136 9137@table @asis 9138 9139@item @code{-gnateL} 9140 9141This switch turns off the info messages about implicit elaboration pragmas. 9142@end table 9143 9144@geindex -gnatem (gcc) 9145 9146 9147@table @asis 9148 9149@item @code{-gnatem=@emph{path}} 9150 9151Specify a mapping file 9152(the equal sign is optional) 9153(@ref{e8,,Units to Sources Mapping Files}). 9154@end table 9155 9156@geindex -gnatep (gcc) 9157 9158 9159@table @asis 9160 9161@item @code{-gnatep=@emph{file}} 9162 9163Specify a preprocessing data file 9164(the equal sign is optional) 9165(@ref{90,,Integrated Preprocessing}). 9166@end table 9167 9168@geindex -gnateP (gcc) 9169 9170 9171@table @asis 9172 9173@item @code{-gnateP} 9174 9175Turn categorization dependency errors into warnings. 9176Ada requires that units that WITH one another have compatible categories, for 9177example a Pure unit cannot WITH a Preelaborate unit. If this switch is used, 9178these errors become warnings (which can be ignored, or suppressed in the usual 9179manner). This can be useful in some specialized circumstances such as the 9180temporary use of special test software. 9181@end table 9182 9183@geindex -gnateS (gcc) 9184 9185 9186@table @asis 9187 9188@item @code{-gnateS} 9189 9190Synonym of @code{-fdump-scos}, kept for backwards compatibility. 9191@end table 9192 9193@geindex -gnatet=file (gcc) 9194 9195 9196@table @asis 9197 9198@item @code{-gnatet=@emph{path}} 9199 9200Generate target dependent information. The format of the output file is 9201described in the section about switch @code{-gnateT}. 9202@end table 9203 9204@geindex -gnateT (gcc) 9205 9206 9207@table @asis 9208 9209@item @code{-gnateT=@emph{path}} 9210 9211Read target dependent information, such as endianness or sizes and alignments 9212of base type. If this switch is passed, the default target dependent 9213information of the compiler is replaced by the one read from the input file. 9214This is used by tools other than the compiler, e.g. to do 9215semantic analysis of programs that will run on some other target than 9216the machine on which the tool is run. 9217 9218The following target dependent values should be defined, 9219where @code{Nat} denotes a natural integer value, @code{Pos} denotes a 9220positive integer value, and fields marked with a question mark are 9221boolean fields, where a value of 0 is False, and a value of 1 is True: 9222 9223@example 9224Bits_BE : Nat; -- Bits stored big-endian? 9225Bits_Per_Unit : Pos; -- Bits in a storage unit 9226Bits_Per_Word : Pos; -- Bits in a word 9227Bytes_BE : Nat; -- Bytes stored big-endian? 9228Char_Size : Pos; -- Standard.Character'Size 9229Double_Float_Alignment : Nat; -- Alignment of double float 9230Double_Scalar_Alignment : Nat; -- Alignment of double length scalar 9231Double_Size : Pos; -- Standard.Long_Float'Size 9232Float_Size : Pos; -- Standard.Float'Size 9233Float_Words_BE : Nat; -- Float words stored big-endian? 9234Int_Size : Pos; -- Standard.Integer'Size 9235Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size 9236Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size 9237Long_Size : Pos; -- Standard.Long_Integer'Size 9238Maximum_Alignment : Pos; -- Maximum permitted alignment 9239Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field 9240Pointer_Size : Pos; -- System.Address'Size 9241Short_Enums : Nat; -- Foreign enums use short size? 9242Short_Size : Pos; -- Standard.Short_Integer'Size 9243Strict_Alignment : Nat; -- Strict alignment? 9244System_Allocator_Alignment : Nat; -- Alignment for malloc calls 9245Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size 9246Words_BE : Nat; -- Words stored big-endian? 9247@end example 9248 9249@code{Bits_Per_Unit} is the number of bits in a storage unit, the equivalent of 9250GCC macro @code{BITS_PER_UNIT} documented as follows: @cite{Define this macro to be the number of bits in an addressable storage unit (byte); normally 8.} 9251 9252@code{Bits_Per_Word} is the number of bits in a machine word, the equivalent of 9253GCC macro @code{BITS_PER_WORD} documented as follows: @cite{Number of bits in a word; normally 32.} 9254 9255@code{Double_Float_Alignment}, if not zero, is the maximum alignment that the 9256compiler can choose by default for a 64-bit floating-point type or object. 9257 9258@code{Double_Scalar_Alignment}, if not zero, is the maximum alignment that the 9259compiler can choose by default for a 64-bit or larger scalar type or object. 9260 9261@code{Maximum_Alignment} is the maximum alignment that the compiler can choose 9262by default for a type or object, which is also the maximum alignment that can 9263be specified in GNAT. It is computed for GCC backends as @code{BIGGEST_ALIGNMENT 9264/ BITS_PER_UNIT} where GCC macro @code{BIGGEST_ALIGNMENT} is documented as 9265follows: @cite{Biggest alignment that any data type can require on this machine@comma{} in bits.} 9266 9267@code{Max_Unaligned_Field} is the maximum size for unaligned bit field, which is 926864 for the majority of GCC targets (but can be different on some targets like 9269AAMP). 9270 9271@code{Strict_Alignment} is the equivalent of GCC macro @code{STRICT_ALIGNMENT} 9272documented as follows: @cite{Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case@comma{} define this macro as 0.} 9273 9274@code{System_Allocator_Alignment} is the guaranteed alignment of data returned 9275by calls to @code{malloc}. 9276 9277The format of the input file is as follows. First come the values of 9278the variables defined above, with one line per value: 9279 9280@example 9281name value 9282@end example 9283 9284where @code{name} is the name of the parameter, spelled out in full, 9285and cased as in the above list, and @code{value} is an unsigned decimal 9286integer. Two or more blanks separates the name from the value. 9287 9288All the variables must be present, in alphabetical order (i.e. the 9289same order as the list above). 9290 9291Then there is a blank line to separate the two parts of the file. Then 9292come the lines showing the floating-point types to be registered, with 9293one line per registered mode: 9294 9295@example 9296name digs float_rep size alignment 9297@end example 9298 9299where @code{name} is the string name of the type (which can have 9300single spaces embedded in the name (e.g. long double), @code{digs} is 9301the number of digits for the floating-point type, @code{float_rep} is 9302the float representation (I/V/A for IEEE-754-Binary, Vax_Native, 9303AAMP), @code{size} is the size in bits, @code{alignment} is the 9304alignment in bits. The name is followed by at least two blanks, fields 9305are separated by at least one blank, and a LF character immediately 9306follows the alignment field. 9307 9308Here is an example of a target parameterization file: 9309 9310@example 9311Bits_BE 0 9312Bits_Per_Unit 8 9313Bits_Per_Word 64 9314Bytes_BE 0 9315Char_Size 8 9316Double_Float_Alignment 0 9317Double_Scalar_Alignment 0 9318Double_Size 64 9319Float_Size 32 9320Float_Words_BE 0 9321Int_Size 64 9322Long_Double_Size 128 9323Long_Long_Size 64 9324Long_Size 64 9325Maximum_Alignment 16 9326Max_Unaligned_Field 64 9327Pointer_Size 64 9328Short_Size 16 9329Strict_Alignment 0 9330System_Allocator_Alignment 16 9331Wchar_T_Size 32 9332Words_BE 0 9333 9334float 15 I 64 64 9335double 15 I 64 64 9336long double 18 I 80 128 9337TF 33 I 128 128 9338@end example 9339@end table 9340 9341@geindex -gnateu (gcc) 9342 9343 9344@table @asis 9345 9346@item @code{-gnateu} 9347 9348Ignore unrecognized validity, warning, and style switches that 9349appear after this switch is given. This may be useful when 9350compiling sources developed on a later version of the compiler 9351with an earlier version. Of course the earlier version must 9352support this switch. 9353@end table 9354 9355@geindex -gnateV (gcc) 9356 9357 9358@table @asis 9359 9360@item @code{-gnateV} 9361 9362Check that all actual parameters of a subprogram call are valid according to 9363the rules of validity checking (@ref{e7,,Validity Checking}). 9364@end table 9365 9366@geindex -gnateY (gcc) 9367 9368 9369@table @asis 9370 9371@item @code{-gnateY} 9372 9373Ignore all STYLE_CHECKS pragmas. Full legality checks 9374are still carried out, but the pragmas have no effect 9375on what style checks are active. This allows all style 9376checking options to be controlled from the command line. 9377@end table 9378 9379@geindex -gnatE (gcc) 9380 9381 9382@table @asis 9383 9384@item @code{-gnatE} 9385 9386Dynamic elaboration checking mode enabled. For further details see 9387@ref{f,,Elaboration Order Handling in GNAT}. 9388@end table 9389 9390@geindex -gnatf (gcc) 9391 9392 9393@table @asis 9394 9395@item @code{-gnatf} 9396 9397Full errors. Multiple errors per line, all undefined references, do not 9398attempt to suppress cascaded errors. 9399@end table 9400 9401@geindex -gnatF (gcc) 9402 9403 9404@table @asis 9405 9406@item @code{-gnatF} 9407 9408Externals names are folded to all uppercase. 9409@end table 9410 9411@geindex -gnatg (gcc) 9412 9413 9414@table @asis 9415 9416@item @code{-gnatg} 9417 9418Internal GNAT implementation mode. This should not be used for applications 9419programs, it is intended only for use by the compiler and its run-time 9420library. For documentation, see the GNAT sources. Note that @code{-gnatg} 9421implies @code{-gnatw.ge} and @code{-gnatyg} so that all standard 9422warnings and all standard style options are turned on. All warnings and style 9423messages are treated as errors. 9424@end table 9425 9426@geindex -gnatG[nn] (gcc) 9427 9428 9429@table @asis 9430 9431@item @code{-gnatG=nn} 9432 9433List generated expanded code in source form. 9434@end table 9435 9436@geindex -gnath (gcc) 9437 9438 9439@table @asis 9440 9441@item @code{-gnath} 9442 9443Output usage information. The output is written to @code{stdout}. 9444@end table 9445 9446@geindex -gnatH (gcc) 9447 9448 9449@table @asis 9450 9451@item @code{-gnatH} 9452 9453Legacy elaboration-checking mode enabled. When this switch is in effect, 9454the pre-18.x access-before-elaboration model becomes the de facto model. 9455For further details see @ref{f,,Elaboration Order Handling in GNAT}. 9456@end table 9457 9458@geindex -gnati (gcc) 9459 9460 9461@table @asis 9462 9463@item @code{-gnati@emph{c}} 9464 9465Identifier character set (@code{c} = 1/2/3/4/8/9/p/f/n/w). 9466For details of the possible selections for @code{c}, 9467see @ref{31,,Character Set Control}. 9468@end table 9469 9470@geindex -gnatI (gcc) 9471 9472 9473@table @asis 9474 9475@item @code{-gnatI} 9476 9477Ignore representation clauses. When this switch is used, 9478representation clauses are treated as comments. This is useful 9479when initially porting code where you want to ignore rep clause 9480problems, and also for compiling foreign code (particularly 9481for use with ASIS). The representation clauses that are ignored 9482are: enumeration_representation_clause, record_representation_clause, 9483and attribute_definition_clause for the following attributes: 9484Address, Alignment, Bit_Order, Component_Size, Machine_Radix, 9485Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size, 9486and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored. 9487Note that this option should be used only for compiling -- the 9488code is likely to malfunction at run time. 9489@end table 9490 9491@geindex -gnatjnn (gcc) 9492 9493 9494@table @asis 9495 9496@item @code{-gnatj@emph{nn}} 9497 9498Reformat error messages to fit on @code{nn} character lines 9499@end table 9500 9501@geindex -gnatJ (gcc) 9502 9503 9504@table @asis 9505 9506@item @code{-gnatJ} 9507 9508Permissive elaboration-checking mode enabled. When this switch is in effect, 9509the post-18.x access-before-elaboration model ignores potential issues with: 9510 9511 9512@itemize - 9513 9514@item 9515Accept statements 9516 9517@item 9518Activations of tasks defined in instances 9519 9520@item 9521Assertion pragmas 9522 9523@item 9524Calls from within an instance to its enclosing context 9525 9526@item 9527Calls through generic formal parameters 9528 9529@item 9530Calls to subprograms defined in instances 9531 9532@item 9533Entry calls 9534 9535@item 9536Indirect calls using 'Access 9537 9538@item 9539Requeue statements 9540 9541@item 9542Select statements 9543 9544@item 9545Synchronous task suspension 9546@end itemize 9547 9548and does not emit compile-time diagnostics or run-time checks. For further 9549details see @ref{f,,Elaboration Order Handling in GNAT}. 9550@end table 9551 9552@geindex -gnatk (gcc) 9553 9554 9555@table @asis 9556 9557@item @code{-gnatk=@emph{n}} 9558 9559Limit file names to @code{n} (1-999) characters (@code{k} = krunch). 9560@end table 9561 9562@geindex -gnatl (gcc) 9563 9564 9565@table @asis 9566 9567@item @code{-gnatl} 9568 9569Output full source listing with embedded error messages. 9570@end table 9571 9572@geindex -gnatL (gcc) 9573 9574 9575@table @asis 9576 9577@item @code{-gnatL} 9578 9579Used in conjunction with -gnatG or -gnatD to intersperse original 9580source lines (as comment lines with line numbers) in the expanded 9581source output. 9582@end table 9583 9584@geindex -gnatm (gcc) 9585 9586 9587@table @asis 9588 9589@item @code{-gnatm=@emph{n}} 9590 9591Limit number of detected error or warning messages to @code{n} 9592where @code{n} is in the range 1..999999. The default setting if 9593no switch is given is 9999. If the number of warnings reaches this 9594limit, then a message is output and further warnings are suppressed, 9595but the compilation is continued. If the number of error messages 9596reaches this limit, then a message is output and the compilation 9597is abandoned. The equal sign here is optional. A value of zero 9598means that no limit applies. 9599@end table 9600 9601@geindex -gnatn (gcc) 9602 9603 9604@table @asis 9605 9606@item @code{-gnatn[12]} 9607 9608Activate inlining across units for subprograms for which pragma @code{Inline} 9609is specified. This inlining is performed by the GCC back-end. An optional 9610digit sets the inlining level: 1 for moderate inlining across units 9611or 2 for full inlining across units. If no inlining level is specified, 9612the compiler will pick it based on the optimization level. 9613@end table 9614 9615@geindex -gnatN (gcc) 9616 9617 9618@table @asis 9619 9620@item @code{-gnatN} 9621 9622Activate front end inlining for subprograms for which 9623pragma @code{Inline} is specified. This inlining is performed 9624by the front end and will be visible in the 9625@code{-gnatG} output. 9626 9627When using a gcc-based back end (in practice this means using any version 9628of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of 9629@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred. 9630Historically front end inlining was more extensive than the gcc back end 9631inlining, but that is no longer the case. 9632@end table 9633 9634@geindex -gnato0 (gcc) 9635 9636 9637@table @asis 9638 9639@item @code{-gnato0} 9640 9641Suppresses overflow checking. This causes the behavior of the compiler to 9642match the default for older versions where overflow checking was suppressed 9643by default. This is equivalent to having 9644@code{pragma Suppress (Overflow_Check)} in a configuration pragma file. 9645@end table 9646 9647@geindex -gnato?? (gcc) 9648 9649 9650@table @asis 9651 9652@item @code{-gnato??} 9653 9654Set default mode for handling generation of code to avoid intermediate 9655arithmetic overflow. Here @code{??} is two digits, a 9656single digit, or nothing. Each digit is one of the digits @code{1} 9657through @code{3}: 9658 9659 9660@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 9661@item 9662 9663Digit 9664 9665@tab 9666 9667Interpretation 9668 9669@item 9670 9671@emph{1} 9672 9673@tab 9674 9675All intermediate overflows checked against base type (@code{STRICT}) 9676 9677@item 9678 9679@emph{2} 9680 9681@tab 9682 9683Minimize intermediate overflows (@code{MINIMIZED}) 9684 9685@item 9686 9687@emph{3} 9688 9689@tab 9690 9691Eliminate intermediate overflows (@code{ELIMINATED}) 9692 9693@end multitable 9694 9695 9696If only one digit appears, then it applies to all 9697cases; if two digits are given, then the first applies outside 9698assertions, pre/postconditions, and type invariants, and the second 9699applies within assertions, pre/postconditions, and type invariants. 9700 9701If no digits follow the @code{-gnato}, then it is equivalent to 9702@code{-gnato11}, 9703causing all intermediate overflows to be handled in strict 9704mode. 9705 9706This switch also causes arithmetic overflow checking to be performed 9707(as though @code{pragma Unsuppress (Overflow_Check)} had been specified). 9708 9709The default if no option @code{-gnato} is given is that overflow handling 9710is in @code{STRICT} mode (computations done using the base type), and that 9711overflow checking is enabled. 9712 9713Note that division by zero is a separate check that is not 9714controlled by this switch (divide-by-zero checking is on by default). 9715 9716See also @ref{e9,,Specifying the Desired Mode}. 9717@end table 9718 9719@geindex -gnatp (gcc) 9720 9721 9722@table @asis 9723 9724@item @code{-gnatp} 9725 9726Suppress all checks. See @ref{ea,,Run-Time Checks} for details. This switch 9727has no effect if cancelled by a subsequent @code{-gnat-p} switch. 9728@end table 9729 9730@geindex -gnat-p (gcc) 9731 9732 9733@table @asis 9734 9735@item @code{-gnat-p} 9736 9737Cancel effect of previous @code{-gnatp} switch. 9738@end table 9739 9740@geindex -gnatq (gcc) 9741 9742 9743@table @asis 9744 9745@item @code{-gnatq} 9746 9747Don't quit. Try semantics, even if parse errors. 9748@end table 9749 9750@geindex -gnatQ (gcc) 9751 9752 9753@table @asis 9754 9755@item @code{-gnatQ} 9756 9757Don't quit. Generate @code{ALI} and tree files even if illegalities. 9758Note that code generation is still suppressed in the presence of any 9759errors, so even with @code{-gnatQ} no object file is generated. 9760@end table 9761 9762@geindex -gnatr (gcc) 9763 9764 9765@table @asis 9766 9767@item @code{-gnatr} 9768 9769Treat pragma Restrictions as Restriction_Warnings. 9770@end table 9771 9772@geindex -gnatR (gcc) 9773 9774 9775@table @asis 9776 9777@item @code{-gnatR[0|1|2|3|4][e][j][m][s]} 9778 9779Output representation information for declared types, objects and 9780subprograms. Note that this switch is not allowed if a previous 9781@code{-gnatD} switch has been given, since these two switches 9782are not compatible. 9783@end table 9784 9785@geindex -gnats (gcc) 9786 9787 9788@table @asis 9789 9790@item @code{-gnats} 9791 9792Syntax check only. 9793@end table 9794 9795@geindex -gnatS (gcc) 9796 9797 9798@table @asis 9799 9800@item @code{-gnatS} 9801 9802Print package Standard. 9803@end table 9804 9805@geindex -gnatT (gcc) 9806 9807 9808@table @asis 9809 9810@item @code{-gnatT@emph{nnn}} 9811 9812All compiler tables start at @code{nnn} times usual starting size. 9813@end table 9814 9815@geindex -gnatu (gcc) 9816 9817 9818@table @asis 9819 9820@item @code{-gnatu} 9821 9822List units for this compilation. 9823@end table 9824 9825@geindex -gnatU (gcc) 9826 9827 9828@table @asis 9829 9830@item @code{-gnatU} 9831 9832Tag all error messages with the unique string 'error:' 9833@end table 9834 9835@geindex -gnatv (gcc) 9836 9837 9838@table @asis 9839 9840@item @code{-gnatv} 9841 9842Verbose mode. Full error output with source lines to @code{stdout}. 9843@end table 9844 9845@geindex -gnatV (gcc) 9846 9847 9848@table @asis 9849 9850@item @code{-gnatV} 9851 9852Control level of validity checking (@ref{e7,,Validity Checking}). 9853@end table 9854 9855@geindex -gnatw (gcc) 9856 9857 9858@table @asis 9859 9860@item @code{-gnatw@emph{xxx}} 9861 9862Warning mode where 9863@code{xxx} is a string of option letters that denotes 9864the exact warnings that 9865are enabled or disabled (@ref{eb,,Warning Message Control}). 9866@end table 9867 9868@geindex -gnatW (gcc) 9869 9870 9871@table @asis 9872 9873@item @code{-gnatW@emph{e}} 9874 9875Wide character encoding method 9876(@code{e}=n/h/u/s/e/8). 9877@end table 9878 9879@geindex -gnatx (gcc) 9880 9881 9882@table @asis 9883 9884@item @code{-gnatx} 9885 9886Suppress generation of cross-reference information. 9887@end table 9888 9889@geindex -gnatX (gcc) 9890 9891 9892@table @asis 9893 9894@item @code{-gnatX} 9895 9896Enable GNAT implementation extensions and latest Ada version. 9897@end table 9898 9899@geindex -gnaty (gcc) 9900 9901 9902@table @asis 9903 9904@item @code{-gnaty} 9905 9906Enable built-in style checks (@ref{ec,,Style Checking}). 9907@end table 9908 9909@geindex -gnatz (gcc) 9910 9911 9912@table @asis 9913 9914@item @code{-gnatz@emph{m}} 9915 9916Distribution stub generation and compilation 9917(@code{m}=r/c for receiver/caller stubs). 9918@end table 9919 9920@geindex -I (gcc) 9921 9922 9923@table @asis 9924 9925@item @code{-I@emph{dir}} 9926 9927@geindex RTL 9928 9929Direct GNAT to search the @code{dir} directory for source files needed by 9930the current compilation 9931(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). 9932@end table 9933 9934@geindex -I- (gcc) 9935 9936 9937@table @asis 9938 9939@item @code{-I-} 9940 9941@geindex RTL 9942 9943Except for the source file named in the command line, do not look for source 9944files in the directory containing the source file named in the command line 9945(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). 9946@end table 9947 9948@geindex -o (gcc) 9949 9950 9951@table @asis 9952 9953@item @code{-o @emph{file}} 9954 9955This switch is used in @code{gcc} to redirect the generated object file 9956and its associated ALI file. Beware of this switch with GNAT, because it may 9957cause the object file and ALI file to have different names which in turn 9958may confuse the binder and the linker. 9959@end table 9960 9961@geindex -nostdinc (gcc) 9962 9963 9964@table @asis 9965 9966@item @code{-nostdinc} 9967 9968Inhibit the search of the default location for the GNAT Run Time 9969Library (RTL) source files. 9970@end table 9971 9972@geindex -nostdlib (gcc) 9973 9974 9975@table @asis 9976 9977@item @code{-nostdlib} 9978 9979Inhibit the search of the default location for the GNAT Run Time 9980Library (RTL) ALI files. 9981@end table 9982 9983@geindex -O (gcc) 9984 9985 9986@table @asis 9987 9988@item @code{-O[@emph{n}]} 9989 9990@code{n} controls the optimization level: 9991 9992 9993@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 9994@item 9995 9996@emph{n} 9997 9998@tab 9999 10000Effect 10001 10002@item 10003 10004@emph{0} 10005 10006@tab 10007 10008No optimization, the default setting if no @code{-O} appears 10009 10010@item 10011 10012@emph{1} 10013 10014@tab 10015 10016Normal optimization, the default if you specify @code{-O} without an 10017operand. A good compromise between code quality and compilation 10018time. 10019 10020@item 10021 10022@emph{2} 10023 10024@tab 10025 10026Extensive optimization, may improve execution time, possibly at 10027the cost of substantially increased compilation time. 10028 10029@item 10030 10031@emph{3} 10032 10033@tab 10034 10035Same as @code{-O2}, and also includes inline expansion for small 10036subprograms in the same unit. 10037 10038@item 10039 10040@emph{s} 10041 10042@tab 10043 10044Optimize space usage 10045 10046@end multitable 10047 10048 10049See also @ref{ed,,Optimization Levels}. 10050@end table 10051 10052@geindex -pass-exit-codes (gcc) 10053 10054 10055@table @asis 10056 10057@item @code{-pass-exit-codes} 10058 10059Catch exit codes from the compiler and use the most meaningful as 10060exit status. 10061@end table 10062 10063@geindex --RTS (gcc) 10064 10065 10066@table @asis 10067 10068@item @code{--RTS=@emph{rts-path}} 10069 10070Specifies the default location of the run-time library. Same meaning as the 10071equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}). 10072@end table 10073 10074@geindex -S (gcc) 10075 10076 10077@table @asis 10078 10079@item @code{-S} 10080 10081Used in place of @code{-c} to 10082cause the assembler source file to be 10083generated, using @code{.s} as the extension, 10084instead of the object file. 10085This may be useful if you need to examine the generated assembly code. 10086@end table 10087 10088@geindex -fverbose-asm (gcc) 10089 10090 10091@table @asis 10092 10093@item @code{-fverbose-asm} 10094 10095Used in conjunction with @code{-S} 10096to cause the generated assembly code file to be annotated with variable 10097names, making it significantly easier to follow. 10098@end table 10099 10100@geindex -v (gcc) 10101 10102 10103@table @asis 10104 10105@item @code{-v} 10106 10107Show commands generated by the @code{gcc} driver. Normally used only for 10108debugging purposes or if you need to be sure what version of the 10109compiler you are executing. 10110@end table 10111 10112@geindex -V (gcc) 10113 10114 10115@table @asis 10116 10117@item @code{-V @emph{ver}} 10118 10119Execute @code{ver} version of the compiler. This is the @code{gcc} 10120version, not the GNAT version. 10121@end table 10122 10123@geindex -w (gcc) 10124 10125 10126@table @asis 10127 10128@item @code{-w} 10129 10130Turn off warnings generated by the back end of the compiler. Use of 10131this switch also causes the default for front end warnings to be set 10132to suppress (as though @code{-gnatws} had appeared at the start of 10133the options). 10134@end table 10135 10136@geindex Combining GNAT switches 10137 10138You may combine a sequence of GNAT switches into a single switch. For 10139example, the combined switch 10140 10141@quotation 10142 10143@example 10144-gnatofi3 10145@end example 10146@end quotation 10147 10148is equivalent to specifying the following sequence of switches: 10149 10150@quotation 10151 10152@example 10153-gnato -gnatf -gnati3 10154@end example 10155@end quotation 10156 10157The following restrictions apply to the combination of switches 10158in this manner: 10159 10160 10161@itemize * 10162 10163@item 10164The switch @code{-gnatc} if combined with other switches must come 10165first in the string. 10166 10167@item 10168The switch @code{-gnats} if combined with other switches must come 10169first in the string. 10170 10171@item 10172The switches 10173@code{-gnatzc} and @code{-gnatzr} may not be combined with any other 10174switches, and only one of them may appear in the command line. 10175 10176@item 10177The switch @code{-gnat-p} may not be combined with any other switch. 10178 10179@item 10180Once a 'y' appears in the string (that is a use of the @code{-gnaty} 10181switch), then all further characters in the switch are interpreted 10182as style modifiers (see description of @code{-gnaty}). 10183 10184@item 10185Once a 'd' appears in the string (that is a use of the @code{-gnatd} 10186switch), then all further characters in the switch are interpreted 10187as debug flags (see description of @code{-gnatd}). 10188 10189@item 10190Once a 'w' appears in the string (that is a use of the @code{-gnatw} 10191switch), then all further characters in the switch are interpreted 10192as warning mode modifiers (see description of @code{-gnatw}). 10193 10194@item 10195Once a 'V' appears in the string (that is a use of the @code{-gnatV} 10196switch), then all further characters in the switch are interpreted 10197as validity checking options (@ref{e7,,Validity Checking}). 10198 10199@item 10200Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in 10201a combined list of options. 10202@end itemize 10203 10204@node Output and Error Message Control,Warning Message Control,Alphabetical List of All Switches,Compiler Switches 10205@anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{ee}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{ef} 10206@subsection Output and Error Message Control 10207 10208 10209@geindex stderr 10210 10211The standard default format for error messages is called 'brief format'. 10212Brief format messages are written to @code{stderr} (the standard error 10213file) and have the following form: 10214 10215@example 10216e.adb:3:04: Incorrect spelling of keyword "function" 10217e.adb:4:20: ";" should be "is" 10218@end example 10219 10220The first integer after the file name is the line number in the file, 10221and the second integer is the column number within the line. 10222@code{GNAT Studio} can parse the error messages 10223and point to the referenced character. 10224The following switches provide control over the error message 10225format: 10226 10227@geindex -gnatv (gcc) 10228 10229 10230@table @asis 10231 10232@item @code{-gnatv} 10233 10234The @code{v} stands for verbose. 10235The effect of this setting is to write long-format error 10236messages to @code{stdout} (the standard output file. 10237The same program compiled with the 10238@code{-gnatv} switch would generate: 10239 10240@example 102413. funcion X (Q : Integer) 10242 | 10243>>> Incorrect spelling of keyword "function" 102444. return Integer; 10245 | 10246>>> ";" should be "is" 10247@end example 10248 10249The vertical bar indicates the location of the error, and the @code{>>>} 10250prefix can be used to search for error messages. When this switch is 10251used the only source lines output are those with errors. 10252@end table 10253 10254@geindex -gnatl (gcc) 10255 10256 10257@table @asis 10258 10259@item @code{-gnatl} 10260 10261The @code{l} stands for list. 10262This switch causes a full listing of 10263the file to be generated. In the case where a body is 10264compiled, the corresponding spec is also listed, along 10265with any subunits. Typical output from compiling a package 10266body @code{p.adb} might look like: 10267 10268@example 10269Compiling: p.adb 10270 10271 1. package body p is 10272 2. procedure a; 10273 3. procedure a is separate; 10274 4. begin 10275 5. null 10276 | 10277 >>> missing ";" 10278 10279 6. end; 10280 10281Compiling: p.ads 10282 10283 1. package p is 10284 2. pragma Elaborate_Body 10285 | 10286 >>> missing ";" 10287 10288 3. end p; 10289 10290Compiling: p-a.adb 10291 10292 1. separate p 10293 | 10294 >>> missing "(" 10295 10296 2. procedure a is 10297 3. begin 10298 4. null 10299 | 10300 >>> missing ";" 10301 10302 5. end; 10303@end example 10304 10305When you specify the @code{-gnatv} or @code{-gnatl} switches and 10306standard output is redirected, a brief summary is written to 10307@code{stderr} (standard error) giving the number of error messages and 10308warning messages generated. 10309@end table 10310 10311@geindex -gnatl=fname (gcc) 10312 10313 10314@table @asis 10315 10316@item @code{-gnatl=@emph{fname}} 10317 10318This has the same effect as @code{-gnatl} except that the output is 10319written to a file instead of to standard output. If the given name 10320@code{fname} does not start with a period, then it is the full name 10321of the file to be written. If @code{fname} is an extension, it is 10322appended to the name of the file being compiled. For example, if 10323file @code{xyz.adb} is compiled with @code{-gnatl=.lst}, 10324then the output is written to file xyz.adb.lst. 10325@end table 10326 10327@geindex -gnatU (gcc) 10328 10329 10330@table @asis 10331 10332@item @code{-gnatU} 10333 10334This switch forces all error messages to be preceded by the unique 10335string 'error:'. This means that error messages take a few more 10336characters in space, but allows easy searching for and identification 10337of error messages. 10338@end table 10339 10340@geindex -gnatb (gcc) 10341 10342 10343@table @asis 10344 10345@item @code{-gnatb} 10346 10347The @code{b} stands for brief. 10348This switch causes GNAT to generate the 10349brief format error messages to @code{stderr} (the standard error 10350file) as well as the verbose 10351format message or full listing (which as usual is written to 10352@code{stdout} (the standard output file). 10353@end table 10354 10355@geindex -gnatm (gcc) 10356 10357 10358@table @asis 10359 10360@item @code{-gnatm=@emph{n}} 10361 10362The @code{m} stands for maximum. 10363@code{n} is a decimal integer in the 10364range of 1 to 999999 and limits the number of error or warning 10365messages to be generated. For example, using 10366@code{-gnatm2} might yield 10367 10368@example 10369e.adb:3:04: Incorrect spelling of keyword "function" 10370e.adb:5:35: missing ".." 10371fatal error: maximum number of errors detected 10372compilation abandoned 10373@end example 10374 10375The default setting if 10376no switch is given is 9999. If the number of warnings reaches this 10377limit, then a message is output and further warnings are suppressed, 10378but the compilation is continued. If the number of error messages 10379reaches this limit, then a message is output and the compilation 10380is abandoned. A value of zero means that no limit applies. 10381 10382Note that the equal sign is optional, so the switches 10383@code{-gnatm2} and @code{-gnatm=2} are equivalent. 10384@end table 10385 10386@geindex -gnatf (gcc) 10387 10388 10389@table @asis 10390 10391@item @code{-gnatf} 10392 10393@geindex Error messages 10394@geindex suppressing 10395 10396The @code{f} stands for full. 10397Normally, the compiler suppresses error messages that are likely to be 10398redundant. This switch causes all error 10399messages to be generated. In particular, in the case of 10400references to undefined variables. If a given variable is referenced 10401several times, the normal format of messages is 10402 10403@example 10404e.adb:7:07: "V" is undefined (more references follow) 10405@end example 10406 10407where the parenthetical comment warns that there are additional 10408references to the variable @code{V}. Compiling the same program with the 10409@code{-gnatf} switch yields 10410 10411@example 10412e.adb:7:07: "V" is undefined 10413e.adb:8:07: "V" is undefined 10414e.adb:8:12: "V" is undefined 10415e.adb:8:16: "V" is undefined 10416e.adb:9:07: "V" is undefined 10417e.adb:9:12: "V" is undefined 10418@end example 10419 10420The @code{-gnatf} switch also generates additional information for 10421some error messages. Some examples are: 10422 10423 10424@itemize * 10425 10426@item 10427Details on possibly non-portable unchecked conversion 10428 10429@item 10430List possible interpretations for ambiguous calls 10431 10432@item 10433Additional details on incorrect parameters 10434@end itemize 10435@end table 10436 10437@geindex -gnatjnn (gcc) 10438 10439 10440@table @asis 10441 10442@item @code{-gnatjnn} 10443 10444In normal operation mode (or if @code{-gnatj0} is used), then error messages 10445with continuation lines are treated as though the continuation lines were 10446separate messages (and so a warning with two continuation lines counts as 10447three warnings, and is listed as three separate messages). 10448 10449If the @code{-gnatjnn} switch is used with a positive value for nn, then 10450messages are output in a different manner. A message and all its continuation 10451lines are treated as a unit, and count as only one warning or message in the 10452statistics totals. Furthermore, the message is reformatted so that no line 10453is longer than nn characters. 10454@end table 10455 10456@geindex -gnatq (gcc) 10457 10458 10459@table @asis 10460 10461@item @code{-gnatq} 10462 10463The @code{q} stands for quit (really 'don't quit'). 10464In normal operation mode, the compiler first parses the program and 10465determines if there are any syntax errors. If there are, appropriate 10466error messages are generated and compilation is immediately terminated. 10467This switch tells 10468GNAT to continue with semantic analysis even if syntax errors have been 10469found. This may enable the detection of more errors in a single run. On 10470the other hand, the semantic analyzer is more likely to encounter some 10471internal fatal error when given a syntactically invalid tree. 10472@end table 10473 10474@geindex -gnatQ (gcc) 10475 10476 10477@table @asis 10478 10479@item @code{-gnatQ} 10480 10481In normal operation mode, the @code{ALI} file is not generated if any 10482illegalities are detected in the program. The use of @code{-gnatQ} forces 10483generation of the @code{ALI} file. This file is marked as being in 10484error, so it cannot be used for binding purposes, but it does contain 10485reasonably complete cross-reference information, and thus may be useful 10486for use by tools (e.g., semantic browsing tools or integrated development 10487environments) that are driven from the @code{ALI} file. This switch 10488implies @code{-gnatq}, since the semantic phase must be run to get a 10489meaningful ALI file. 10490 10491When @code{-gnatQ} is used and the generated @code{ALI} file is marked as 10492being in error, @code{gnatmake} will attempt to recompile the source when it 10493finds such an @code{ALI} file, including with switch @code{-gnatc}. 10494 10495Note that @code{-gnatQ} has no effect if @code{-gnats} is specified, 10496since ALI files are never generated if @code{-gnats} is set. 10497@end table 10498 10499@node Warning Message Control,Debugging and Assertion Control,Output and Error Message Control,Compiler Switches 10500@anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{eb}@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{f0} 10501@subsection Warning Message Control 10502 10503 10504@geindex Warning messages 10505 10506In addition to error messages, which correspond to illegalities as defined 10507in the Ada Reference Manual, the compiler detects two kinds of warning 10508situations. 10509 10510First, the compiler considers some constructs suspicious and generates a 10511warning message to alert you to a possible error. Second, if the 10512compiler detects a situation that is sure to raise an exception at 10513run time, it generates a warning message. The following shows an example 10514of warning messages: 10515 10516@example 10517e.adb:4:24: warning: creation of object may raise Storage_Error 10518e.adb:10:17: warning: static value out of range 10519e.adb:10:17: warning: "Constraint_Error" will be raised at run time 10520@end example 10521 10522GNAT considers a large number of situations as appropriate 10523for the generation of warning messages. As always, warnings are not 10524definite indications of errors. For example, if you do an out-of-range 10525assignment with the deliberate intention of raising a 10526@code{Constraint_Error} exception, then the warning that may be 10527issued does not indicate an error. Some of the situations for which GNAT 10528issues warnings (at least some of the time) are given in the following 10529list. This list is not complete, and new warnings are often added to 10530subsequent versions of GNAT. The list is intended to give a general idea 10531of the kinds of warnings that are generated. 10532 10533 10534@itemize * 10535 10536@item 10537Possible infinitely recursive calls 10538 10539@item 10540Out-of-range values being assigned 10541 10542@item 10543Possible order of elaboration problems 10544 10545@item 10546Size not a multiple of alignment for a record type 10547 10548@item 10549Assertions (pragma Assert) that are sure to fail 10550 10551@item 10552Unreachable code 10553 10554@item 10555Address clauses with possibly unaligned values, or where an attempt is 10556made to overlay a smaller variable with a larger one. 10557 10558@item 10559Fixed-point type declarations with a null range 10560 10561@item 10562Direct_IO or Sequential_IO instantiated with a type that has access values 10563 10564@item 10565Variables that are never assigned a value 10566 10567@item 10568Variables that are referenced before being initialized 10569 10570@item 10571Task entries with no corresponding @code{accept} statement 10572 10573@item 10574Duplicate accepts for the same task entry in a @code{select} 10575 10576@item 10577Objects that take too much storage 10578 10579@item 10580Unchecked conversion between types of differing sizes 10581 10582@item 10583Missing @code{return} statement along some execution path in a function 10584 10585@item 10586Incorrect (unrecognized) pragmas 10587 10588@item 10589Incorrect external names 10590 10591@item 10592Allocation from empty storage pool 10593 10594@item 10595Potentially blocking operation in protected type 10596 10597@item 10598Suspicious parenthesization of expressions 10599 10600@item 10601Mismatching bounds in an aggregate 10602 10603@item 10604Attempt to return local value by reference 10605 10606@item 10607Premature instantiation of a generic body 10608 10609@item 10610Attempt to pack aliased components 10611 10612@item 10613Out of bounds array subscripts 10614 10615@item 10616Wrong length on string assignment 10617 10618@item 10619Violations of style rules if style checking is enabled 10620 10621@item 10622Unused @emph{with} clauses 10623 10624@item 10625@code{Bit_Order} usage that does not have any effect 10626 10627@item 10628@code{Standard.Duration} used to resolve universal fixed expression 10629 10630@item 10631Dereference of possibly null value 10632 10633@item 10634Declaration that is likely to cause storage error 10635 10636@item 10637Internal GNAT unit @emph{with}ed by application unit 10638 10639@item 10640Values known to be out of range at compile time 10641 10642@item 10643Unreferenced or unmodified variables. Note that a special 10644exemption applies to variables which contain any of the substrings 10645@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED}, in any casing. Such variables 10646are considered likely to be intentionally used in a situation where 10647otherwise a warning would be given, so warnings of this kind are 10648always suppressed for such variables. 10649 10650@item 10651Address overlays that could clobber memory 10652 10653@item 10654Unexpected initialization when address clause present 10655 10656@item 10657Bad alignment for address clause 10658 10659@item 10660Useless type conversions 10661 10662@item 10663Redundant assignment statements and other redundant constructs 10664 10665@item 10666Useless exception handlers 10667 10668@item 10669Accidental hiding of name by child unit 10670 10671@item 10672Access before elaboration detected at compile time 10673 10674@item 10675A range in a @code{for} loop that is known to be null or might be null 10676@end itemize 10677 10678The following section lists compiler switches that are available 10679to control the handling of warning messages. It is also possible 10680to exercise much finer control over what warnings are issued and 10681suppressed using the GNAT pragma Warnings (see the description 10682of the pragma in the @cite{GNAT_Reference_manual}). 10683 10684@geindex -gnatwa (gcc) 10685 10686 10687@table @asis 10688 10689@item @code{-gnatwa} 10690 10691@emph{Activate most optional warnings.} 10692 10693This switch activates most optional warning messages. See the remaining list 10694in this section for details on optional warning messages that can be 10695individually controlled. The warnings that are not turned on by this 10696switch are: 10697 10698 10699@itemize * 10700 10701@item 10702@code{-gnatwd} (implicit dereferencing) 10703 10704@item 10705@code{-gnatw.d} (tag warnings with -gnatw switch) 10706 10707@item 10708@code{-gnatwh} (hiding) 10709 10710@item 10711@code{-gnatw.h} (holes in record layouts) 10712 10713@item 10714@code{-gnatw.j} (late primitives of tagged types) 10715 10716@item 10717@code{-gnatw.k} (redefinition of names in standard) 10718 10719@item 10720@code{-gnatwl} (elaboration warnings) 10721 10722@item 10723@code{-gnatw.l} (inherited aspects) 10724 10725@item 10726@code{-gnatw.n} (atomic synchronization) 10727 10728@item 10729@code{-gnatwo} (address clause overlay) 10730 10731@item 10732@code{-gnatw.o} (values set by out parameters ignored) 10733 10734@item 10735@code{-gnatw.q} (questionable layout of record types) 10736 10737@item 10738@code{-gnatw_r} (out-of-order record representation clauses) 10739 10740@item 10741@code{-gnatw.s} (overridden size clause) 10742 10743@item 10744@code{-gnatwt} (tracking of deleted conditional code) 10745 10746@item 10747@code{-gnatw.u} (unordered enumeration) 10748 10749@item 10750@code{-gnatw.w} (use of Warnings Off) 10751 10752@item 10753@code{-gnatw.y} (reasons for package needing body) 10754@end itemize 10755 10756All other optional warnings are turned on. 10757@end table 10758 10759@geindex -gnatwA (gcc) 10760 10761 10762@table @asis 10763 10764@item @code{-gnatwA} 10765 10766@emph{Suppress all optional errors.} 10767 10768This switch suppresses all optional warning messages, see remaining list 10769in this section for details on optional warning messages that can be 10770individually controlled. Note that unlike switch @code{-gnatws}, the 10771use of switch @code{-gnatwA} does not suppress warnings that are 10772normally given unconditionally and cannot be individually controlled 10773(for example, the warning about a missing exit path in a function). 10774Also, again unlike switch @code{-gnatws}, warnings suppressed by 10775the use of switch @code{-gnatwA} can be individually turned back 10776on. For example the use of switch @code{-gnatwA} followed by 10777switch @code{-gnatwd} will suppress all optional warnings except 10778the warnings for implicit dereferencing. 10779@end table 10780 10781@geindex -gnatw.a (gcc) 10782 10783 10784@table @asis 10785 10786@item @code{-gnatw.a} 10787 10788@emph{Activate warnings on failing assertions.} 10789 10790@geindex Assert failures 10791 10792This switch activates warnings for assertions where the compiler can tell at 10793compile time that the assertion will fail. Note that this warning is given 10794even if assertions are disabled. The default is that such warnings are 10795generated. 10796@end table 10797 10798@geindex -gnatw.A (gcc) 10799 10800 10801@table @asis 10802 10803@item @code{-gnatw.A} 10804 10805@emph{Suppress warnings on failing assertions.} 10806 10807@geindex Assert failures 10808 10809This switch suppresses warnings for assertions where the compiler can tell at 10810compile time that the assertion will fail. 10811@end table 10812 10813@geindex -gnatw_a 10814 10815 10816@table @asis 10817 10818@item @code{-gnatw_a} 10819 10820@emph{Activate warnings on anonymous allocators.} 10821 10822@geindex Anonymous allocators 10823 10824This switch activates warnings for allocators of anonymous access types, 10825which can involve run-time accessibility checks and lead to unexpected 10826accessibility violations. For more details on the rules involved, see 10827RM 3.10.2 (14). 10828@end table 10829 10830@geindex -gnatw_A 10831 10832 10833@table @asis 10834 10835@item @code{-gnatw_A} 10836 10837@emph{Supress warnings on anonymous allocators.} 10838 10839@geindex Anonymous allocators 10840 10841This switch suppresses warnings for anonymous access type allocators. 10842@end table 10843 10844@geindex -gnatwb (gcc) 10845 10846 10847@table @asis 10848 10849@item @code{-gnatwb} 10850 10851@emph{Activate warnings on bad fixed values.} 10852 10853@geindex Bad fixed values 10854 10855@geindex Fixed-point Small value 10856 10857@geindex Small value 10858 10859This switch activates warnings for static fixed-point expressions whose 10860value is not an exact multiple of Small. Such values are implementation 10861dependent, since an implementation is free to choose either of the multiples 10862that surround the value. GNAT always chooses the closer one, but this is not 10863required behavior, and it is better to specify a value that is an exact 10864multiple, ensuring predictable execution. The default is that such warnings 10865are not generated. 10866@end table 10867 10868@geindex -gnatwB (gcc) 10869 10870 10871@table @asis 10872 10873@item @code{-gnatwB} 10874 10875@emph{Suppress warnings on bad fixed values.} 10876 10877This switch suppresses warnings for static fixed-point expressions whose 10878value is not an exact multiple of Small. 10879@end table 10880 10881@geindex -gnatw.b (gcc) 10882 10883 10884@table @asis 10885 10886@item @code{-gnatw.b} 10887 10888@emph{Activate warnings on biased representation.} 10889 10890@geindex Biased representation 10891 10892This switch activates warnings when a size clause, value size clause, component 10893clause, or component size clause forces the use of biased representation for an 10894integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 10895to represent 10/11). The default is that such warnings are generated. 10896@end table 10897 10898@geindex -gnatwB (gcc) 10899 10900 10901@table @asis 10902 10903@item @code{-gnatw.B} 10904 10905@emph{Suppress warnings on biased representation.} 10906 10907This switch suppresses warnings for representation clauses that force the use 10908of biased representation. 10909@end table 10910 10911@geindex -gnatwc (gcc) 10912 10913 10914@table @asis 10915 10916@item @code{-gnatwc} 10917 10918@emph{Activate warnings on conditionals.} 10919 10920@geindex Conditionals 10921@geindex constant 10922 10923This switch activates warnings for conditional expressions used in 10924tests that are known to be True or False at compile time. The default 10925is that such warnings are not generated. 10926Note that this warning does 10927not get issued for the use of boolean variables or constants whose 10928values are known at compile time, since this is a standard technique 10929for conditional compilation in Ada, and this would generate too many 10930false positive warnings. 10931 10932This warning option also activates a special test for comparisons using 10933the operators '>=' and' <='. 10934If the compiler can tell that only the equality condition is possible, 10935then it will warn that the '>' or '<' part of the test 10936is useless and that the operator could be replaced by '='. 10937An example would be comparing a @code{Natural} variable <= 0. 10938 10939This warning option also generates warnings if 10940one or both tests is optimized away in a membership test for integer 10941values if the result can be determined at compile time. Range tests on 10942enumeration types are not included, since it is common for such tests 10943to include an end point. 10944 10945This warning can also be turned on using @code{-gnatwa}. 10946@end table 10947 10948@geindex -gnatwC (gcc) 10949 10950 10951@table @asis 10952 10953@item @code{-gnatwC} 10954 10955@emph{Suppress warnings on conditionals.} 10956 10957This switch suppresses warnings for conditional expressions used in 10958tests that are known to be True or False at compile time. 10959@end table 10960 10961@geindex -gnatw.c (gcc) 10962 10963 10964@table @asis 10965 10966@item @code{-gnatw.c} 10967 10968@emph{Activate warnings on missing component clauses.} 10969 10970@geindex Component clause 10971@geindex missing 10972 10973This switch activates warnings for record components where a record 10974representation clause is present and has component clauses for the 10975majority, but not all, of the components. A warning is given for each 10976component for which no component clause is present. 10977@end table 10978 10979@geindex -gnatw.C (gcc) 10980 10981 10982@table @asis 10983 10984@item @code{-gnatw.C} 10985 10986@emph{Suppress warnings on missing component clauses.} 10987 10988This switch suppresses warnings for record components that are 10989missing a component clause in the situation described above. 10990@end table 10991 10992@geindex -gnatw_c (gcc) 10993 10994 10995@table @asis 10996 10997@item @code{-gnatw_c} 10998 10999@emph{Activate warnings on unknown condition in Compile_Time_Warning.} 11000 11001@geindex Compile_Time_Warning 11002 11003@geindex Compile_Time_Error 11004 11005This switch activates warnings on a pragma Compile_Time_Warning 11006or Compile_Time_Error whose condition has a value that is not 11007known at compile time. 11008The default is that such warnings are generated. 11009@end table 11010 11011@geindex -gnatw_C (gcc) 11012 11013 11014@table @asis 11015 11016@item @code{-gnatw_C} 11017 11018@emph{Suppress warnings on unknown condition in Compile_Time_Warning.} 11019 11020This switch supresses warnings on a pragma Compile_Time_Warning 11021or Compile_Time_Error whose condition has a value that is not 11022known at compile time. 11023@end table 11024 11025@geindex -gnatwd (gcc) 11026 11027 11028@table @asis 11029 11030@item @code{-gnatwd} 11031 11032@emph{Activate warnings on implicit dereferencing.} 11033 11034If this switch is set, then the use of a prefix of an access type 11035in an indexed component, slice, or selected component without an 11036explicit @code{.all} will generate a warning. With this warning 11037enabled, access checks occur only at points where an explicit 11038@code{.all} appears in the source code (assuming no warnings are 11039generated as a result of this switch). The default is that such 11040warnings are not generated. 11041@end table 11042 11043@geindex -gnatwD (gcc) 11044 11045 11046@table @asis 11047 11048@item @code{-gnatwD} 11049 11050@emph{Suppress warnings on implicit dereferencing.} 11051 11052@geindex Implicit dereferencing 11053 11054@geindex Dereferencing 11055@geindex implicit 11056 11057This switch suppresses warnings for implicit dereferences in 11058indexed components, slices, and selected components. 11059@end table 11060 11061@geindex -gnatw.d (gcc) 11062 11063 11064@table @asis 11065 11066@item @code{-gnatw.d} 11067 11068@emph{Activate tagging of warning and info messages.} 11069 11070If this switch is set, then warning messages are tagged, with one of the 11071following strings: 11072 11073@quotation 11074 11075 11076@itemize - 11077 11078@item 11079@emph{[-gnatw?]} 11080Used to tag warnings controlled by the switch @code{-gnatwx} where x 11081is a letter a-z. 11082 11083@item 11084@emph{[-gnatw.?]} 11085Used to tag warnings controlled by the switch @code{-gnatw.x} where x 11086is a letter a-z. 11087 11088@item 11089@emph{[-gnatel]} 11090Used to tag elaboration information (info) messages generated when the 11091static model of elaboration is used and the @code{-gnatel} switch is set. 11092 11093@item 11094@emph{[restriction warning]} 11095Used to tag warning messages for restriction violations, activated by use 11096of the pragma @code{Restriction_Warnings}. 11097 11098@item 11099@emph{[warning-as-error]} 11100Used to tag warning messages that have been converted to error messages by 11101use of the pragma Warning_As_Error. Note that such warnings are prefixed by 11102the string "error: " rather than "warning: ". 11103 11104@item 11105@emph{[enabled by default]} 11106Used to tag all other warnings that are always given by default, unless 11107warnings are completely suppressed using pragma @emph{Warnings(Off)} or 11108the switch @code{-gnatws}. 11109@end itemize 11110@end quotation 11111@end table 11112 11113@geindex -gnatw.d (gcc) 11114 11115 11116@table @asis 11117 11118@item @code{-gnatw.D} 11119 11120@emph{Deactivate tagging of warning and info messages messages.} 11121 11122If this switch is set, then warning messages return to the default 11123mode in which warnings and info messages are not tagged as described above for 11124@code{-gnatw.d}. 11125@end table 11126 11127@geindex -gnatwe (gcc) 11128 11129@geindex Warnings 11130@geindex treat as error 11131 11132 11133@table @asis 11134 11135@item @code{-gnatwe} 11136 11137@emph{Treat warnings and style checks as errors.} 11138 11139This switch causes warning messages and style check messages to be 11140treated as errors. 11141The warning string still appears, but the warning messages are counted 11142as errors, and prevent the generation of an object file. Note that this 11143is the only -gnatw switch that affects the handling of style check messages. 11144Note also that this switch has no effect on info (information) messages, which 11145are not treated as errors if this switch is present. 11146@end table 11147 11148@geindex -gnatw.e (gcc) 11149 11150 11151@table @asis 11152 11153@item @code{-gnatw.e} 11154 11155@emph{Activate every optional warning.} 11156 11157@geindex Warnings 11158@geindex activate every optional warning 11159 11160This switch activates all optional warnings, including those which 11161are not activated by @code{-gnatwa}. The use of this switch is not 11162recommended for normal use. If you turn this switch on, it is almost 11163certain that you will get large numbers of useless warnings. The 11164warnings that are excluded from @code{-gnatwa} are typically highly 11165specialized warnings that are suitable for use only in code that has 11166been specifically designed according to specialized coding rules. 11167@end table 11168 11169@geindex -gnatwE (gcc) 11170 11171@geindex Warnings 11172@geindex treat as error 11173 11174 11175@table @asis 11176 11177@item @code{-gnatwE} 11178 11179@emph{Treat all run-time exception warnings as errors.} 11180 11181This switch causes warning messages regarding errors that will be raised 11182during run-time execution to be treated as errors. 11183@end table 11184 11185@geindex -gnatwf (gcc) 11186 11187 11188@table @asis 11189 11190@item @code{-gnatwf} 11191 11192@emph{Activate warnings on unreferenced formals.} 11193 11194@geindex Formals 11195@geindex unreferenced 11196 11197This switch causes a warning to be generated if a formal parameter 11198is not referenced in the body of the subprogram. This warning can 11199also be turned on using @code{-gnatwu}. The 11200default is that these warnings are not generated. 11201@end table 11202 11203@geindex -gnatwF (gcc) 11204 11205 11206@table @asis 11207 11208@item @code{-gnatwF} 11209 11210@emph{Suppress warnings on unreferenced formals.} 11211 11212This switch suppresses warnings for unreferenced formal 11213parameters. Note that the 11214combination @code{-gnatwu} followed by @code{-gnatwF} has the 11215effect of warning on unreferenced entities other than subprogram 11216formals. 11217@end table 11218 11219@geindex -gnatwg (gcc) 11220 11221 11222@table @asis 11223 11224@item @code{-gnatwg} 11225 11226@emph{Activate warnings on unrecognized pragmas.} 11227 11228@geindex Pragmas 11229@geindex unrecognized 11230 11231This switch causes a warning to be generated if an unrecognized 11232pragma is encountered. Apart from issuing this warning, the 11233pragma is ignored and has no effect. The default 11234is that such warnings are issued (satisfying the Ada Reference 11235Manual requirement that such warnings appear). 11236@end table 11237 11238@geindex -gnatwG (gcc) 11239 11240 11241@table @asis 11242 11243@item @code{-gnatwG} 11244 11245@emph{Suppress warnings on unrecognized pragmas.} 11246 11247This switch suppresses warnings for unrecognized pragmas. 11248@end table 11249 11250@geindex -gnatw.g (gcc) 11251 11252 11253@table @asis 11254 11255@item @code{-gnatw.g} 11256 11257@emph{Warnings used for GNAT sources.} 11258 11259This switch sets the warning categories that are used by the standard 11260GNAT style. Currently this is equivalent to 11261@code{-gnatwAao.q.s.CI.V.X.Z} 11262but more warnings may be added in the future without advanced notice. 11263@end table 11264 11265@geindex -gnatwh (gcc) 11266 11267 11268@table @asis 11269 11270@item @code{-gnatwh} 11271 11272@emph{Activate warnings on hiding.} 11273 11274@geindex Hiding of Declarations 11275 11276This switch activates warnings on hiding declarations that are considered 11277potentially confusing. Not all cases of hiding cause warnings; for example an 11278overriding declaration hides an implicit declaration, which is just normal 11279code. The default is that warnings on hiding are not generated. 11280@end table 11281 11282@geindex -gnatwH (gcc) 11283 11284 11285@table @asis 11286 11287@item @code{-gnatwH} 11288 11289@emph{Suppress warnings on hiding.} 11290 11291This switch suppresses warnings on hiding declarations. 11292@end table 11293 11294@geindex -gnatw.h (gcc) 11295 11296 11297@table @asis 11298 11299@item @code{-gnatw.h} 11300 11301@emph{Activate warnings on holes/gaps in records.} 11302 11303@geindex Record Representation (gaps) 11304 11305This switch activates warnings on component clauses in record 11306representation clauses that leave holes (gaps) in the record layout. 11307If this warning option is active, then record representation clauses 11308should specify a contiguous layout, adding unused fill fields if needed. 11309@end table 11310 11311@geindex -gnatw.H (gcc) 11312 11313 11314@table @asis 11315 11316@item @code{-gnatw.H} 11317 11318@emph{Suppress warnings on holes/gaps in records.} 11319 11320This switch suppresses warnings on component clauses in record 11321representation clauses that leave holes (haps) in the record layout. 11322@end table 11323 11324@geindex -gnatwi (gcc) 11325 11326 11327@table @asis 11328 11329@item @code{-gnatwi} 11330 11331@emph{Activate warnings on implementation units.} 11332 11333This switch activates warnings for a @emph{with} of an internal GNAT 11334implementation unit, defined as any unit from the @code{Ada}, 11335@code{Interfaces}, @code{GNAT}, 11336or @code{System} 11337hierarchies that is not 11338documented in either the Ada Reference Manual or the GNAT 11339Programmer's Reference Manual. Such units are intended only 11340for internal implementation purposes and should not be @emph{with}ed 11341by user programs. The default is that such warnings are generated 11342@end table 11343 11344@geindex -gnatwI (gcc) 11345 11346 11347@table @asis 11348 11349@item @code{-gnatwI} 11350 11351@emph{Disable warnings on implementation units.} 11352 11353This switch disables warnings for a @emph{with} of an internal GNAT 11354implementation unit. 11355@end table 11356 11357@geindex -gnatw.i (gcc) 11358 11359 11360@table @asis 11361 11362@item @code{-gnatw.i} 11363 11364@emph{Activate warnings on overlapping actuals.} 11365 11366This switch enables a warning on statically detectable overlapping actuals in 11367a subprogram call, when one of the actuals is an in-out parameter, and the 11368types of the actuals are not by-copy types. This warning is off by default. 11369@end table 11370 11371@geindex -gnatw.I (gcc) 11372 11373 11374@table @asis 11375 11376@item @code{-gnatw.I} 11377 11378@emph{Disable warnings on overlapping actuals.} 11379 11380This switch disables warnings on overlapping actuals in a call.. 11381@end table 11382 11383@geindex -gnatwj (gcc) 11384 11385 11386@table @asis 11387 11388@item @code{-gnatwj} 11389 11390@emph{Activate warnings on obsolescent features (Annex J).} 11391 11392@geindex Features 11393@geindex obsolescent 11394 11395@geindex Obsolescent features 11396 11397If this warning option is activated, then warnings are generated for 11398calls to subprograms marked with @code{pragma Obsolescent} and 11399for use of features in Annex J of the Ada Reference Manual. In the 11400case of Annex J, not all features are flagged. In particular use 11401of the renamed packages (like @code{Text_IO}) and use of package 11402@code{ASCII} are not flagged, since these are very common and 11403would generate many annoying positive warnings. The default is that 11404such warnings are not generated. 11405 11406In addition to the above cases, warnings are also generated for 11407GNAT features that have been provided in past versions but which 11408have been superseded (typically by features in the new Ada standard). 11409For example, @code{pragma Ravenscar} will be flagged since its 11410function is replaced by @code{pragma Profile(Ravenscar)}, and 11411@code{pragma Interface_Name} will be flagged since its function 11412is replaced by @code{pragma Import}. 11413 11414Note that this warning option functions differently from the 11415restriction @code{No_Obsolescent_Features} in two respects. 11416First, the restriction applies only to annex J features. 11417Second, the restriction does flag uses of package @code{ASCII}. 11418@end table 11419 11420@geindex -gnatwJ (gcc) 11421 11422 11423@table @asis 11424 11425@item @code{-gnatwJ} 11426 11427@emph{Suppress warnings on obsolescent features (Annex J).} 11428 11429This switch disables warnings on use of obsolescent features. 11430@end table 11431 11432@geindex -gnatw.j (gcc) 11433 11434 11435@table @asis 11436 11437@item @code{-gnatw.j} 11438 11439@emph{Activate warnings on late declarations of tagged type primitives.} 11440 11441This switch activates warnings on visible primitives added to a 11442tagged type after deriving a private extension from it. 11443@end table 11444 11445@geindex -gnatw.J (gcc) 11446 11447 11448@table @asis 11449 11450@item @code{-gnatw.J} 11451 11452@emph{Suppress warnings on late declarations of tagged type primitives.} 11453 11454This switch suppresses warnings on visible primitives added to a 11455tagged type after deriving a private extension from it. 11456@end table 11457 11458@geindex -gnatwk (gcc) 11459 11460 11461@table @asis 11462 11463@item @code{-gnatwk} 11464 11465@emph{Activate warnings on variables that could be constants.} 11466 11467This switch activates warnings for variables that are initialized but 11468never modified, and then could be declared constants. The default is that 11469such warnings are not given. 11470@end table 11471 11472@geindex -gnatwK (gcc) 11473 11474 11475@table @asis 11476 11477@item @code{-gnatwK} 11478 11479@emph{Suppress warnings on variables that could be constants.} 11480 11481This switch disables warnings on variables that could be declared constants. 11482@end table 11483 11484@geindex -gnatw.k (gcc) 11485 11486 11487@table @asis 11488 11489@item @code{-gnatw.k} 11490 11491@emph{Activate warnings on redefinition of names in standard.} 11492 11493This switch activates warnings for declarations that declare a name that 11494is defined in package Standard. Such declarations can be confusing, 11495especially since the names in package Standard continue to be directly 11496visible, meaning that use visibiliy on such redeclared names does not 11497work as expected. Names of discriminants and components in records are 11498not included in this check. 11499@end table 11500 11501@geindex -gnatwK (gcc) 11502 11503 11504@table @asis 11505 11506@item @code{-gnatw.K} 11507 11508@emph{Suppress warnings on redefinition of names in standard.} 11509 11510This switch disables warnings for declarations that declare a name that 11511is defined in package Standard. 11512@end table 11513 11514@geindex -gnatwl (gcc) 11515 11516 11517@table @asis 11518 11519@item @code{-gnatwl} 11520 11521@emph{Activate warnings for elaboration pragmas.} 11522 11523@geindex Elaboration 11524@geindex warnings 11525 11526This switch activates warnings for possible elaboration problems, 11527including suspicious use 11528of @code{Elaborate} pragmas, when using the static elaboration model, and 11529possible situations that may raise @code{Program_Error} when using the 11530dynamic elaboration model. 11531See the section in this guide on elaboration checking for further details. 11532The default is that such warnings 11533are not generated. 11534@end table 11535 11536@geindex -gnatwL (gcc) 11537 11538 11539@table @asis 11540 11541@item @code{-gnatwL} 11542 11543@emph{Suppress warnings for elaboration pragmas.} 11544 11545This switch suppresses warnings for possible elaboration problems. 11546@end table 11547 11548@geindex -gnatw.l (gcc) 11549 11550 11551@table @asis 11552 11553@item @code{-gnatw.l} 11554 11555@emph{List inherited aspects.} 11556 11557This switch causes the compiler to list inherited invariants, 11558preconditions, and postconditions from Type_Invariant'Class, Invariant'Class, 11559Pre'Class, and Post'Class aspects. Also list inherited subtype predicates. 11560@end table 11561 11562@geindex -gnatw.L (gcc) 11563 11564 11565@table @asis 11566 11567@item @code{-gnatw.L} 11568 11569@emph{Suppress listing of inherited aspects.} 11570 11571This switch suppresses listing of inherited aspects. 11572@end table 11573 11574@geindex -gnatwm (gcc) 11575 11576 11577@table @asis 11578 11579@item @code{-gnatwm} 11580 11581@emph{Activate warnings on modified but unreferenced variables.} 11582 11583This switch activates warnings for variables that are assigned (using 11584an initialization value or with one or more assignment statements) but 11585whose value is never read. The warning is suppressed for volatile 11586variables and also for variables that are renamings of other variables 11587or for which an address clause is given. 11588The default is that these warnings are not given. 11589@end table 11590 11591@geindex -gnatwM (gcc) 11592 11593 11594@table @asis 11595 11596@item @code{-gnatwM} 11597 11598@emph{Disable warnings on modified but unreferenced variables.} 11599 11600This switch disables warnings for variables that are assigned or 11601initialized, but never read. 11602@end table 11603 11604@geindex -gnatw.m (gcc) 11605 11606 11607@table @asis 11608 11609@item @code{-gnatw.m} 11610 11611@emph{Activate warnings on suspicious modulus values.} 11612 11613This switch activates warnings for modulus values that seem suspicious. 11614The cases caught are where the size is the same as the modulus (e.g. 11615a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 11616with no size clause. The guess in both cases is that 2**x was intended 11617rather than x. In addition expressions of the form 2*x for small x 11618generate a warning (the almost certainly accurate guess being that 116192**x was intended). The default is that these warnings are given. 11620@end table 11621 11622@geindex -gnatw.M (gcc) 11623 11624 11625@table @asis 11626 11627@item @code{-gnatw.M} 11628 11629@emph{Disable warnings on suspicious modulus values.} 11630 11631This switch disables warnings for suspicious modulus values. 11632@end table 11633 11634@geindex -gnatwn (gcc) 11635 11636 11637@table @asis 11638 11639@item @code{-gnatwn} 11640 11641@emph{Set normal warnings mode.} 11642 11643This switch sets normal warning mode, in which enabled warnings are 11644issued and treated as warnings rather than errors. This is the default 11645mode. the switch @code{-gnatwn} can be used to cancel the effect of 11646an explicit @code{-gnatws} or 11647@code{-gnatwe}. It also cancels the effect of the 11648implicit @code{-gnatwe} that is activated by the 11649use of @code{-gnatg}. 11650@end table 11651 11652@geindex -gnatw.n (gcc) 11653 11654@geindex Atomic Synchronization 11655@geindex warnings 11656 11657 11658@table @asis 11659 11660@item @code{-gnatw.n} 11661 11662@emph{Activate warnings on atomic synchronization.} 11663 11664This switch actives warnings when an access to an atomic variable 11665requires the generation of atomic synchronization code. These 11666warnings are off by default. 11667@end table 11668 11669@geindex -gnatw.N (gcc) 11670 11671 11672@table @asis 11673 11674@item @code{-gnatw.N} 11675 11676@emph{Suppress warnings on atomic synchronization.} 11677 11678@geindex Atomic Synchronization 11679@geindex warnings 11680 11681This switch suppresses warnings when an access to an atomic variable 11682requires the generation of atomic synchronization code. 11683@end table 11684 11685@geindex -gnatwo (gcc) 11686 11687@geindex Address Clauses 11688@geindex warnings 11689 11690 11691@table @asis 11692 11693@item @code{-gnatwo} 11694 11695@emph{Activate warnings on address clause overlays.} 11696 11697This switch activates warnings for possibly unintended initialization 11698effects of defining address clauses that cause one variable to overlap 11699another. The default is that such warnings are generated. 11700@end table 11701 11702@geindex -gnatwO (gcc) 11703 11704 11705@table @asis 11706 11707@item @code{-gnatwO} 11708 11709@emph{Suppress warnings on address clause overlays.} 11710 11711This switch suppresses warnings on possibly unintended initialization 11712effects of defining address clauses that cause one variable to overlap 11713another. 11714@end table 11715 11716@geindex -gnatw.o (gcc) 11717 11718 11719@table @asis 11720 11721@item @code{-gnatw.o} 11722 11723@emph{Activate warnings on modified but unreferenced out parameters.} 11724 11725This switch activates warnings for variables that are modified by using 11726them as actuals for a call to a procedure with an out mode formal, where 11727the resulting assigned value is never read. It is applicable in the case 11728where there is more than one out mode formal. If there is only one out 11729mode formal, the warning is issued by default (controlled by -gnatwu). 11730The warning is suppressed for volatile 11731variables and also for variables that are renamings of other variables 11732or for which an address clause is given. 11733The default is that these warnings are not given. 11734@end table 11735 11736@geindex -gnatw.O (gcc) 11737 11738 11739@table @asis 11740 11741@item @code{-gnatw.O} 11742 11743@emph{Disable warnings on modified but unreferenced out parameters.} 11744 11745This switch suppresses warnings for variables that are modified by using 11746them as actuals for a call to a procedure with an out mode formal, where 11747the resulting assigned value is never read. 11748@end table 11749 11750@geindex -gnatwp (gcc) 11751 11752@geindex Inlining 11753@geindex warnings 11754 11755 11756@table @asis 11757 11758@item @code{-gnatwp} 11759 11760@emph{Activate warnings on ineffective pragma Inlines.} 11761 11762This switch activates warnings for failure of front end inlining 11763(activated by @code{-gnatN}) to inline a particular call. There are 11764many reasons for not being able to inline a call, including most 11765commonly that the call is too complex to inline. The default is 11766that such warnings are not given. 11767Warnings on ineffective inlining by the gcc back-end can be activated 11768separately, using the gcc switch -Winline. 11769@end table 11770 11771@geindex -gnatwP (gcc) 11772 11773 11774@table @asis 11775 11776@item @code{-gnatwP} 11777 11778@emph{Suppress warnings on ineffective pragma Inlines.} 11779 11780This switch suppresses warnings on ineffective pragma Inlines. If the 11781inlining mechanism cannot inline a call, it will simply ignore the 11782request silently. 11783@end table 11784 11785@geindex -gnatw.p (gcc) 11786 11787@geindex Parameter order 11788@geindex warnings 11789 11790 11791@table @asis 11792 11793@item @code{-gnatw.p} 11794 11795@emph{Activate warnings on parameter ordering.} 11796 11797This switch activates warnings for cases of suspicious parameter 11798ordering when the list of arguments are all simple identifiers that 11799match the names of the formals, but are in a different order. The 11800warning is suppressed if any use of named parameter notation is used, 11801so this is the appropriate way to suppress a false positive (and 11802serves to emphasize that the "misordering" is deliberate). The 11803default is that such warnings are not given. 11804@end table 11805 11806@geindex -gnatw.P (gcc) 11807 11808 11809@table @asis 11810 11811@item @code{-gnatw.P} 11812 11813@emph{Suppress warnings on parameter ordering.} 11814 11815This switch suppresses warnings on cases of suspicious parameter 11816ordering. 11817@end table 11818 11819@geindex -gnatwq (gcc) 11820 11821@geindex Parentheses 11822@geindex warnings 11823 11824 11825@table @asis 11826 11827@item @code{-gnatwq} 11828 11829@emph{Activate warnings on questionable missing parentheses.} 11830 11831This switch activates warnings for cases where parentheses are not used and 11832the result is potential ambiguity from a readers point of view. For example 11833(not a > b) when a and b are modular means ((not a) > b) and very likely the 11834programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and 11835quite likely ((-x) mod 5) was intended. In such situations it seems best to 11836follow the rule of always parenthesizing to make the association clear, and 11837this warning switch warns if such parentheses are not present. The default 11838is that these warnings are given. 11839@end table 11840 11841@geindex -gnatwQ (gcc) 11842 11843 11844@table @asis 11845 11846@item @code{-gnatwQ} 11847 11848@emph{Suppress warnings on questionable missing parentheses.} 11849 11850This switch suppresses warnings for cases where the association is not 11851clear and the use of parentheses is preferred. 11852@end table 11853 11854@geindex -gnatw.q (gcc) 11855 11856@geindex Layout 11857@geindex warnings 11858 11859 11860@table @asis 11861 11862@item @code{-gnatw.q} 11863 11864@emph{Activate warnings on questionable layout of record types.} 11865 11866This switch activates warnings for cases where the default layout of 11867a record type, that is to say the layout of its components in textual 11868order of the source code, would very likely cause inefficiencies in 11869the code generated by the compiler, both in terms of space and speed 11870during execution. One warning is issued for each problematic component 11871without representation clause in the nonvariant part and then in each 11872variant recursively, if any. 11873 11874The purpose of these warnings is neither to prescribe an optimal layout 11875nor to force the use of representation clauses, but rather to get rid of 11876the most blatant inefficiencies in the layout. Therefore, the default 11877layout is matched against the following synthetic ordered layout and 11878the deviations are flagged on a component-by-component basis: 11879 11880 11881@itemize * 11882 11883@item 11884first all components or groups of components whose length is fixed 11885and a multiple of the storage unit, 11886 11887@item 11888then the remaining components whose length is fixed and not a multiple 11889of the storage unit, 11890 11891@item 11892then the remaining components whose length doesn't depend on discriminants 11893(that is to say, with variable but uniform length for all objects), 11894 11895@item 11896then all components whose length depends on discriminants, 11897 11898@item 11899finally the variant part (if any), 11900@end itemize 11901 11902for the nonvariant part and for each variant recursively, if any. 11903 11904The exact wording of the warning depends on whether the compiler is allowed 11905to reorder the components in the record type or precluded from doing it by 11906means of pragma @code{No_Component_Reordering}. 11907 11908The default is that these warnings are not given. 11909@end table 11910 11911@geindex -gnatw.Q (gcc) 11912 11913 11914@table @asis 11915 11916@item @code{-gnatw.Q} 11917 11918@emph{Suppress warnings on questionable layout of record types.} 11919 11920This switch suppresses warnings for cases where the default layout of 11921a record type would very likely cause inefficiencies. 11922@end table 11923 11924@geindex -gnatwr (gcc) 11925 11926 11927@table @asis 11928 11929@item @code{-gnatwr} 11930 11931@emph{Activate warnings on redundant constructs.} 11932 11933This switch activates warnings for redundant constructs. The following 11934is the current list of constructs regarded as redundant: 11935 11936 11937@itemize * 11938 11939@item 11940Assignment of an item to itself. 11941 11942@item 11943Type conversion that converts an expression to its own type. 11944 11945@item 11946Use of the attribute @code{Base} where @code{typ'Base} is the same 11947as @code{typ}. 11948 11949@item 11950Use of pragma @code{Pack} when all components are placed by a record 11951representation clause. 11952 11953@item 11954Exception handler containing only a reraise statement (raise with no 11955operand) which has no effect. 11956 11957@item 11958Use of the operator abs on an operand that is known at compile time 11959to be non-negative 11960 11961@item 11962Comparison of an object or (unary or binary) operation of boolean type to 11963an explicit True value. 11964@end itemize 11965 11966The default is that warnings for redundant constructs are not given. 11967@end table 11968 11969@geindex -gnatwR (gcc) 11970 11971 11972@table @asis 11973 11974@item @code{-gnatwR} 11975 11976@emph{Suppress warnings on redundant constructs.} 11977 11978This switch suppresses warnings for redundant constructs. 11979@end table 11980 11981@geindex -gnatw.r (gcc) 11982 11983 11984@table @asis 11985 11986@item @code{-gnatw.r} 11987 11988@emph{Activate warnings for object renaming function.} 11989 11990This switch activates warnings for an object renaming that renames a 11991function call, which is equivalent to a constant declaration (as 11992opposed to renaming the function itself). The default is that these 11993warnings are given. 11994@end table 11995 11996@geindex -gnatw.R (gcc) 11997 11998 11999@table @asis 12000 12001@item @code{-gnatw.R} 12002 12003@emph{Suppress warnings for object renaming function.} 12004 12005This switch suppresses warnings for object renaming function. 12006@end table 12007 12008@geindex -gnatw_r (gcc) 12009 12010 12011@table @asis 12012 12013@item @code{-gnatw_r} 12014 12015@emph{Activate warnings for out-of-order record representation clauses.} 12016 12017This switch activates warnings for record representation clauses, 12018if the order of component declarations, component clauses, 12019and bit-level layout do not all agree. 12020The default is that these warnings are not given. 12021@end table 12022 12023@geindex -gnatw_R (gcc) 12024 12025 12026@table @asis 12027 12028@item @code{-gnatw_R} 12029 12030@emph{Suppress warnings for out-of-order record representation clauses.} 12031@end table 12032 12033@geindex -gnatws (gcc) 12034 12035 12036@table @asis 12037 12038@item @code{-gnatws} 12039 12040@emph{Suppress all warnings.} 12041 12042This switch completely suppresses the 12043output of all warning messages from the GNAT front end, including 12044both warnings that can be controlled by switches described in this 12045section, and those that are normally given unconditionally. The 12046effect of this suppress action can only be cancelled by a subsequent 12047use of the switch @code{-gnatwn}. 12048 12049Note that switch @code{-gnatws} does not suppress 12050warnings from the @code{gcc} back end. 12051To suppress these back end warnings as well, use the switch @code{-w} 12052in addition to @code{-gnatws}. Also this switch has no effect on the 12053handling of style check messages. 12054@end table 12055 12056@geindex -gnatw.s (gcc) 12057 12058@geindex Record Representation (component sizes) 12059 12060 12061@table @asis 12062 12063@item @code{-gnatw.s} 12064 12065@emph{Activate warnings on overridden size clauses.} 12066 12067This switch activates warnings on component clauses in record 12068representation clauses where the length given overrides that 12069specified by an explicit size clause for the component type. A 12070warning is similarly given in the array case if a specified 12071component size overrides an explicit size clause for the array 12072component type. 12073@end table 12074 12075@geindex -gnatw.S (gcc) 12076 12077 12078@table @asis 12079 12080@item @code{-gnatw.S} 12081 12082@emph{Suppress warnings on overridden size clauses.} 12083 12084This switch suppresses warnings on component clauses in record 12085representation clauses that override size clauses, and similar 12086warnings when an array component size overrides a size clause. 12087@end table 12088 12089@geindex -gnatwt (gcc) 12090 12091@geindex Deactivated code 12092@geindex warnings 12093 12094@geindex Deleted code 12095@geindex warnings 12096 12097 12098@table @asis 12099 12100@item @code{-gnatwt} 12101 12102@emph{Activate warnings for tracking of deleted conditional code.} 12103 12104This switch activates warnings for tracking of code in conditionals (IF and 12105CASE statements) that is detected to be dead code which cannot be executed, and 12106which is removed by the front end. This warning is off by default. This may be 12107useful for detecting deactivated code in certified applications. 12108@end table 12109 12110@geindex -gnatwT (gcc) 12111 12112 12113@table @asis 12114 12115@item @code{-gnatwT} 12116 12117@emph{Suppress warnings for tracking of deleted conditional code.} 12118 12119This switch suppresses warnings for tracking of deleted conditional code. 12120@end table 12121 12122@geindex -gnatw.t (gcc) 12123 12124 12125@table @asis 12126 12127@item @code{-gnatw.t} 12128 12129@emph{Activate warnings on suspicious contracts.} 12130 12131This switch activates warnings on suspicious contracts. This includes 12132warnings on suspicious postconditions (whether a pragma @code{Postcondition} or a 12133@code{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect 12134@code{Contract_Cases}). A function postcondition or contract case is suspicious 12135when no postcondition or contract case for this function mentions the result 12136of the function. A procedure postcondition or contract case is suspicious 12137when it only refers to the pre-state of the procedure, because in that case 12138it should rather be expressed as a precondition. This switch also controls 12139warnings on suspicious cases of expressions typically found in contracts like 12140quantified expressions and uses of Update attribute. The default is that such 12141warnings are generated. 12142@end table 12143 12144@geindex -gnatw.T (gcc) 12145 12146 12147@table @asis 12148 12149@item @code{-gnatw.T} 12150 12151@emph{Suppress warnings on suspicious contracts.} 12152 12153This switch suppresses warnings on suspicious contracts. 12154@end table 12155 12156@geindex -gnatwu (gcc) 12157 12158 12159@table @asis 12160 12161@item @code{-gnatwu} 12162 12163@emph{Activate warnings on unused entities.} 12164 12165This switch activates warnings to be generated for entities that 12166are declared but not referenced, and for units that are @emph{with}ed 12167and not 12168referenced. In the case of packages, a warning is also generated if 12169no entities in the package are referenced. This means that if a with'ed 12170package is referenced but the only references are in @code{use} 12171clauses or @code{renames} 12172declarations, a warning is still generated. A warning is also generated 12173for a generic package that is @emph{with}ed but never instantiated. 12174In the case where a package or subprogram body is compiled, and there 12175is a @emph{with} on the corresponding spec 12176that is only referenced in the body, 12177a warning is also generated, noting that the 12178@emph{with} can be moved to the body. The default is that 12179such warnings are not generated. 12180This switch also activates warnings on unreferenced formals 12181(it includes the effect of @code{-gnatwf}). 12182@end table 12183 12184@geindex -gnatwU (gcc) 12185 12186 12187@table @asis 12188 12189@item @code{-gnatwU} 12190 12191@emph{Suppress warnings on unused entities.} 12192 12193This switch suppresses warnings for unused entities and packages. 12194It also turns off warnings on unreferenced formals (and thus includes 12195the effect of @code{-gnatwF}). 12196@end table 12197 12198@geindex -gnatw.u (gcc) 12199 12200 12201@table @asis 12202 12203@item @code{-gnatw.u} 12204 12205@emph{Activate warnings on unordered enumeration types.} 12206 12207This switch causes enumeration types to be considered as conceptually 12208unordered, unless an explicit pragma @code{Ordered} is given for the type. 12209The effect is to generate warnings in clients that use explicit comparisons 12210or subranges, since these constructs both treat objects of the type as 12211ordered. (A @emph{client} is defined as a unit that is other than the unit in 12212which the type is declared, or its body or subunits.) Please refer to 12213the description of pragma @code{Ordered} in the 12214@cite{GNAT Reference Manual} for further details. 12215The default is that such warnings are not generated. 12216@end table 12217 12218@geindex -gnatw.U (gcc) 12219 12220 12221@table @asis 12222 12223@item @code{-gnatw.U} 12224 12225@emph{Deactivate warnings on unordered enumeration types.} 12226 12227This switch causes all enumeration types to be considered as ordered, so 12228that no warnings are given for comparisons or subranges for any type. 12229@end table 12230 12231@geindex -gnatwv (gcc) 12232 12233@geindex Unassigned variable warnings 12234 12235 12236@table @asis 12237 12238@item @code{-gnatwv} 12239 12240@emph{Activate warnings on unassigned variables.} 12241 12242This switch activates warnings for access to variables which 12243may not be properly initialized. The default is that 12244such warnings are generated. This switch will also be emitted when 12245initializing an array or record object via the following aggregate: 12246 12247@example 12248Array_Or_Record : XXX := (others => <>); 12249@end example 12250 12251unless the relevant type fully initializes all components. 12252@end table 12253 12254@geindex -gnatwV (gcc) 12255 12256 12257@table @asis 12258 12259@item @code{-gnatwV} 12260 12261@emph{Suppress warnings on unassigned variables.} 12262 12263This switch suppresses warnings for access to variables which 12264may not be properly initialized. 12265@end table 12266 12267@geindex -gnatw.v (gcc) 12268 12269@geindex bit order warnings 12270 12271 12272@table @asis 12273 12274@item @code{-gnatw.v} 12275 12276@emph{Activate info messages for non-default bit order.} 12277 12278This switch activates messages (labeled "info", they are not warnings, 12279just informational messages) about the effects of non-default bit-order 12280on records to which a component clause is applied. The effect of specifying 12281non-default bit ordering is a bit subtle (and changed with Ada 2005), so 12282these messages, which are given by default, are useful in understanding the 12283exact consequences of using this feature. 12284@end table 12285 12286@geindex -gnatw.V (gcc) 12287 12288 12289@table @asis 12290 12291@item @code{-gnatw.V} 12292 12293@emph{Suppress info messages for non-default bit order.} 12294 12295This switch suppresses information messages for the effects of specifying 12296non-default bit order on record components with component clauses. 12297@end table 12298 12299@geindex -gnatww (gcc) 12300 12301@geindex String indexing warnings 12302 12303 12304@table @asis 12305 12306@item @code{-gnatww} 12307 12308@emph{Activate warnings on wrong low bound assumption.} 12309 12310This switch activates warnings for indexing an unconstrained string parameter 12311with a literal or S'Length. This is a case where the code is assuming that the 12312low bound is one, which is in general not true (for example when a slice is 12313passed). The default is that such warnings are generated. 12314@end table 12315 12316@geindex -gnatwW (gcc) 12317 12318 12319@table @asis 12320 12321@item @code{-gnatwW} 12322 12323@emph{Suppress warnings on wrong low bound assumption.} 12324 12325This switch suppresses warnings for indexing an unconstrained string parameter 12326with a literal or S'Length. Note that this warning can also be suppressed 12327in a particular case by adding an assertion that the lower bound is 1, 12328as shown in the following example: 12329 12330@example 12331procedure K (S : String) is 12332 pragma Assert (S'First = 1); 12333 ... 12334@end example 12335@end table 12336 12337@geindex -gnatw.w (gcc) 12338 12339@geindex Warnings Off control 12340 12341 12342@table @asis 12343 12344@item @code{-gnatw.w} 12345 12346@emph{Activate warnings on Warnings Off pragmas.} 12347 12348This switch activates warnings for use of @code{pragma Warnings (Off, entity)} 12349where either the pragma is entirely useless (because it suppresses no 12350warnings), or it could be replaced by @code{pragma Unreferenced} or 12351@code{pragma Unmodified}. 12352Also activates warnings for the case of 12353Warnings (Off, String), where either there is no matching 12354Warnings (On, String), or the Warnings (Off) did not suppress any warning. 12355The default is that these warnings are not given. 12356@end table 12357 12358@geindex -gnatw.W (gcc) 12359 12360 12361@table @asis 12362 12363@item @code{-gnatw.W} 12364 12365@emph{Suppress warnings on unnecessary Warnings Off pragmas.} 12366 12367This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}. 12368@end table 12369 12370@geindex -gnatwx (gcc) 12371 12372@geindex Export/Import pragma warnings 12373 12374 12375@table @asis 12376 12377@item @code{-gnatwx} 12378 12379@emph{Activate warnings on Export/Import pragmas.} 12380 12381This switch activates warnings on Export/Import pragmas when 12382the compiler detects a possible conflict between the Ada and 12383foreign language calling sequences. For example, the use of 12384default parameters in a convention C procedure is dubious 12385because the C compiler cannot supply the proper default, so 12386a warning is issued. The default is that such warnings are 12387generated. 12388@end table 12389 12390@geindex -gnatwX (gcc) 12391 12392 12393@table @asis 12394 12395@item @code{-gnatwX} 12396 12397@emph{Suppress warnings on Export/Import pragmas.} 12398 12399This switch suppresses warnings on Export/Import pragmas. 12400The sense of this is that you are telling the compiler that 12401you know what you are doing in writing the pragma, and it 12402should not complain at you. 12403@end table 12404 12405@geindex -gnatwm (gcc) 12406 12407 12408@table @asis 12409 12410@item @code{-gnatw.x} 12411 12412@emph{Activate warnings for No_Exception_Propagation mode.} 12413 12414This switch activates warnings for exception usage when pragma Restrictions 12415(No_Exception_Propagation) is in effect. Warnings are given for implicit or 12416explicit exception raises which are not covered by a local handler, and for 12417exception handlers which do not cover a local raise. The default is that 12418these warnings are given for units that contain exception handlers. 12419 12420@item @code{-gnatw.X} 12421 12422@emph{Disable warnings for No_Exception_Propagation mode.} 12423 12424This switch disables warnings for exception usage when pragma Restrictions 12425(No_Exception_Propagation) is in effect. 12426@end table 12427 12428@geindex -gnatwy (gcc) 12429 12430@geindex Ada compatibility issues warnings 12431 12432 12433@table @asis 12434 12435@item @code{-gnatwy} 12436 12437@emph{Activate warnings for Ada compatibility issues.} 12438 12439For the most part, newer versions of Ada are upwards compatible 12440with older versions. For example, Ada 2005 programs will almost 12441always work when compiled as Ada 2012. 12442However there are some exceptions (for example the fact that 12443@code{some} is now a reserved word in Ada 2012). This 12444switch activates several warnings to help in identifying 12445and correcting such incompatibilities. The default is that 12446these warnings are generated. Note that at one point Ada 2005 12447was called Ada 0Y, hence the choice of character. 12448@end table 12449 12450@geindex -gnatwY (gcc) 12451 12452@geindex Ada compatibility issues warnings 12453 12454 12455@table @asis 12456 12457@item @code{-gnatwY} 12458 12459@emph{Disable warnings for Ada compatibility issues.} 12460 12461This switch suppresses the warnings intended to help in identifying 12462incompatibilities between Ada language versions. 12463@end table 12464 12465@geindex -gnatw.y (gcc) 12466 12467@geindex Package spec needing body 12468 12469 12470@table @asis 12471 12472@item @code{-gnatw.y} 12473 12474@emph{Activate information messages for why package spec needs body.} 12475 12476There are a number of cases in which a package spec needs a body. 12477For example, the use of pragma Elaborate_Body, or the declaration 12478of a procedure specification requiring a completion. This switch 12479causes information messages to be output showing why a package 12480specification requires a body. This can be useful in the case of 12481a large package specification which is unexpectedly requiring a 12482body. The default is that such information messages are not output. 12483@end table 12484 12485@geindex -gnatw.Y (gcc) 12486 12487@geindex No information messages for why package spec needs body 12488 12489 12490@table @asis 12491 12492@item @code{-gnatw.Y} 12493 12494@emph{Disable information messages for why package spec needs body.} 12495 12496This switch suppresses the output of information messages showing why 12497a package specification needs a body. 12498@end table 12499 12500@geindex -gnatwz (gcc) 12501 12502@geindex Unchecked_Conversion warnings 12503 12504 12505@table @asis 12506 12507@item @code{-gnatwz} 12508 12509@emph{Activate warnings on unchecked conversions.} 12510 12511This switch activates warnings for unchecked conversions 12512where the types are known at compile time to have different 12513sizes. The default is that such warnings are generated. Warnings are also 12514generated for subprogram pointers with different conventions. 12515@end table 12516 12517@geindex -gnatwZ (gcc) 12518 12519 12520@table @asis 12521 12522@item @code{-gnatwZ} 12523 12524@emph{Suppress warnings on unchecked conversions.} 12525 12526This switch suppresses warnings for unchecked conversions 12527where the types are known at compile time to have different 12528sizes or conventions. 12529@end table 12530 12531@geindex -gnatw.z (gcc) 12532 12533@geindex Size/Alignment warnings 12534 12535 12536@table @asis 12537 12538@item @code{-gnatw.z} 12539 12540@emph{Activate warnings for size not a multiple of alignment.} 12541 12542This switch activates warnings for cases of array and record types 12543with specified @code{Size} and @code{Alignment} attributes where the 12544size is not a multiple of the alignment, resulting in an object 12545size that is greater than the specified size. The default 12546is that such warnings are generated. 12547@end table 12548 12549@geindex -gnatw.Z (gcc) 12550 12551@geindex Size/Alignment warnings 12552 12553 12554@table @asis 12555 12556@item @code{-gnatw.Z} 12557 12558@emph{Suppress warnings for size not a multiple of alignment.} 12559 12560This switch suppresses warnings for cases of array and record types 12561with specified @code{Size} and @code{Alignment} attributes where the 12562size is not a multiple of the alignment, resulting in an object 12563size that is greater than the specified size. The warning can also 12564be suppressed by giving an explicit @code{Object_Size} value. 12565@end table 12566 12567@geindex -Wunused (gcc) 12568 12569 12570@table @asis 12571 12572@item @code{-Wunused} 12573 12574The warnings controlled by the @code{-gnatw} switch are generated by 12575the front end of the compiler. The GCC back end can provide 12576additional warnings and they are controlled by the @code{-W} switch. 12577For example, @code{-Wunused} activates back end 12578warnings for entities that are declared but not referenced. 12579@end table 12580 12581@geindex -Wuninitialized (gcc) 12582 12583 12584@table @asis 12585 12586@item @code{-Wuninitialized} 12587 12588Similarly, @code{-Wuninitialized} activates 12589the back end warning for uninitialized variables. This switch must be 12590used in conjunction with an optimization level greater than zero. 12591@end table 12592 12593@geindex -Wstack-usage (gcc) 12594 12595 12596@table @asis 12597 12598@item @code{-Wstack-usage=@emph{len}} 12599 12600Warn if the stack usage of a subprogram might be larger than @code{len} bytes. 12601See @ref{e6,,Static Stack Usage Analysis} for details. 12602@end table 12603 12604@geindex -Wall (gcc) 12605 12606 12607@table @asis 12608 12609@item @code{-Wall} 12610 12611This switch enables most warnings from the GCC back end. 12612The code generator detects a number of warning situations that are missed 12613by the GNAT front end, and this switch can be used to activate them. 12614The use of this switch also sets the default front end warning mode to 12615@code{-gnatwa}, that is, most front end warnings activated as well. 12616@end table 12617 12618@geindex -w (gcc) 12619 12620 12621@table @asis 12622 12623@item @code{-w} 12624 12625Conversely, this switch suppresses warnings from the GCC back end. 12626The use of this switch also sets the default front end warning mode to 12627@code{-gnatws}, that is, front end warnings suppressed as well. 12628@end table 12629 12630@geindex -Werror (gcc) 12631 12632 12633@table @asis 12634 12635@item @code{-Werror} 12636 12637This switch causes warnings from the GCC back end to be treated as 12638errors. The warning string still appears, but the warning messages are 12639counted as errors, and prevent the generation of an object file. 12640@end table 12641 12642A string of warning parameters can be used in the same parameter. For example: 12643 12644@example 12645-gnatwaGe 12646@end example 12647 12648will turn on all optional warnings except for unrecognized pragma warnings, 12649and also specify that warnings should be treated as errors. 12650 12651When no switch @code{-gnatw} is used, this is equivalent to: 12652 12653@quotation 12654 12655 12656@itemize * 12657 12658@item 12659@code{-gnatw.a} 12660 12661@item 12662@code{-gnatwB} 12663 12664@item 12665@code{-gnatw.b} 12666 12667@item 12668@code{-gnatwC} 12669 12670@item 12671@code{-gnatw.C} 12672 12673@item 12674@code{-gnatwD} 12675 12676@item 12677@code{-gnatw.D} 12678 12679@item 12680@code{-gnatwF} 12681 12682@item 12683@code{-gnatw.F} 12684 12685@item 12686@code{-gnatwg} 12687 12688@item 12689@code{-gnatwH} 12690 12691@item 12692@code{-gnatw.H} 12693 12694@item 12695@code{-gnatwi} 12696 12697@item 12698@code{-gnatwJ} 12699 12700@item 12701@code{-gnatw.J} 12702 12703@item 12704@code{-gnatwK} 12705 12706@item 12707@code{-gnatw.K} 12708 12709@item 12710@code{-gnatwL} 12711 12712@item 12713@code{-gnatw.L} 12714 12715@item 12716@code{-gnatwM} 12717 12718@item 12719@code{-gnatw.m} 12720 12721@item 12722@code{-gnatwn} 12723 12724@item 12725@code{-gnatw.N} 12726 12727@item 12728@code{-gnatwo} 12729 12730@item 12731@code{-gnatw.O} 12732 12733@item 12734@code{-gnatwP} 12735 12736@item 12737@code{-gnatw.P} 12738 12739@item 12740@code{-gnatwq} 12741 12742@item 12743@code{-gnatw.Q} 12744 12745@item 12746@code{-gnatwR} 12747 12748@item 12749@code{-gnatw.R} 12750 12751@item 12752@code{-gnatw.S} 12753 12754@item 12755@code{-gnatwT} 12756 12757@item 12758@code{-gnatw.t} 12759 12760@item 12761@code{-gnatwU} 12762 12763@item 12764@code{-gnatw.U} 12765 12766@item 12767@code{-gnatwv} 12768 12769@item 12770@code{-gnatw.v} 12771 12772@item 12773@code{-gnatww} 12774 12775@item 12776@code{-gnatw.W} 12777 12778@item 12779@code{-gnatwx} 12780 12781@item 12782@code{-gnatw.X} 12783 12784@item 12785@code{-gnatwy} 12786 12787@item 12788@code{-gnatw.Y} 12789 12790@item 12791@code{-gnatwz} 12792 12793@item 12794@code{-gnatw.z} 12795@end itemize 12796@end quotation 12797 12798@node Debugging and Assertion Control,Validity Checking,Warning Message Control,Compiler Switches 12799@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{f2} 12800@subsection Debugging and Assertion Control 12801 12802 12803@geindex -gnata (gcc) 12804 12805 12806@table @asis 12807 12808@item @code{-gnata} 12809 12810@geindex Assert 12811 12812@geindex Debug 12813 12814@geindex Assertions 12815 12816@geindex Precondition 12817 12818@geindex Postcondition 12819 12820@geindex Type invariants 12821 12822@geindex Subtype predicates 12823 12824The @code{-gnata} option is equivalent to the following @code{Assertion_Policy} pragma: 12825 12826@example 12827pragma Assertion_Policy (Check); 12828@end example 12829 12830Which is a shorthand for: 12831 12832@example 12833pragma Assertion_Policy 12834 (Assert => Check, 12835 Static_Predicate => Check, 12836 Dynamic_Predicate => Check, 12837 Pre => Check, 12838 Pre'Class => Check, 12839 Post => Check, 12840 Post'Class => Check, 12841 Type_Invariant => Check, 12842 Type_Invariant'Class => Check); 12843@end example 12844 12845The pragmas @code{Assert} and @code{Debug} normally have no effect and 12846are ignored. This switch, where @code{a} stands for 'assert', causes 12847pragmas @code{Assert} and @code{Debug} to be activated. This switch also 12848causes preconditions, postconditions, subtype predicates, and 12849type invariants to be activated. 12850 12851The pragmas have the form: 12852 12853@example 12854pragma Assert (<Boolean-expression> [, <static-string-expression>]) 12855pragma Debug (<procedure call>) 12856pragma Type_Invariant (<type-local-name>, <Boolean-expression>) 12857pragma Predicate (<type-local-name>, <Boolean-expression>) 12858pragma Precondition (<Boolean-expression>, <string-expression>) 12859pragma Postcondition (<Boolean-expression>, <string-expression>) 12860@end example 12861 12862The aspects have the form: 12863 12864@example 12865with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate] 12866 => <Boolean-expression>; 12867@end example 12868 12869The @code{Assert} pragma causes @code{Boolean-expression} to be tested. 12870If the result is @code{True}, the pragma has no effect (other than 12871possible side effects from evaluating the expression). If the result is 12872@code{False}, the exception @code{Assert_Failure} declared in the package 12873@code{System.Assertions} is raised (passing @code{static-string-expression}, if 12874present, as the message associated with the exception). If no string 12875expression is given, the default is a string containing the file name and 12876line number of the pragma. 12877 12878The @code{Debug} pragma causes @code{procedure} to be called. Note that 12879@code{pragma Debug} may appear within a declaration sequence, allowing 12880debugging procedures to be called between declarations. 12881 12882For the aspect specification, the @code{Boolean-expression} is evaluated. 12883If the result is @code{True}, the aspect has no effect. If the result 12884is @code{False}, the exception @code{Assert_Failure} is raised. 12885@end table 12886 12887@node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches 12888@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{e7}@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{f3} 12889@subsection Validity Checking 12890 12891 12892@geindex Validity Checking 12893 12894The Ada Reference Manual defines the concept of invalid values (see 12895RM 13.9.1). The primary source of invalid values is uninitialized 12896variables. A scalar variable that is left uninitialized may contain 12897an invalid value; the concept of invalid does not apply to access or 12898composite types. 12899 12900It is an error to read an invalid value, but the RM does not require 12901run-time checks to detect such errors, except for some minimal 12902checking to prevent erroneous execution (i.e. unpredictable 12903behavior). This corresponds to the @code{-gnatVd} switch below, 12904which is the default. For example, by default, if the expression of a 12905case statement is invalid, it will raise Constraint_Error rather than 12906causing a wild jump, and if an array index on the left-hand side of an 12907assignment is invalid, it will raise Constraint_Error rather than 12908overwriting an arbitrary memory location. 12909 12910The @code{-gnatVa} may be used to enable additional validity checks, 12911which are not required by the RM. These checks are often very 12912expensive (which is why the RM does not require them). These checks 12913are useful in tracking down uninitialized variables, but they are 12914not usually recommended for production builds, and in particular 12915we do not recommend using these extra validity checking options in 12916combination with optimization, since this can confuse the optimizer. 12917If performance is a consideration, leading to the need to optimize, 12918then the validity checking options should not be used. 12919 12920The other @code{-gnatV@emph{x}} switches below allow finer-grained 12921control; you can enable whichever validity checks you desire. However, 12922for most debugging purposes, @code{-gnatVa} is sufficient, and the 12923default @code{-gnatVd} (i.e. standard Ada behavior) is usually 12924sufficient for non-debugging use. 12925 12926The @code{-gnatB} switch tells the compiler to assume that all 12927values are valid (that is, within their declared subtype range) 12928except in the context of a use of the Valid attribute. This means 12929the compiler can generate more efficient code, since the range 12930of values is better known at compile time. However, an uninitialized 12931variable can cause wild jumps and memory corruption in this mode. 12932 12933The @code{-gnatV@emph{x}} switch allows control over the validity 12934checking mode as described below. 12935The @code{x} argument is a string of letters that 12936indicate validity checks that are performed or not performed in addition 12937to the default checks required by Ada as described above. 12938 12939@geindex -gnatVa (gcc) 12940 12941 12942@table @asis 12943 12944@item @code{-gnatVa} 12945 12946@emph{All validity checks.} 12947 12948All validity checks are turned on. 12949That is, @code{-gnatVa} is 12950equivalent to @code{gnatVcdfimoprst}. 12951@end table 12952 12953@geindex -gnatVc (gcc) 12954 12955 12956@table @asis 12957 12958@item @code{-gnatVc} 12959 12960@emph{Validity checks for copies.} 12961 12962The right hand side of assignments, and the initializing values of 12963object declarations are validity checked. 12964@end table 12965 12966@geindex -gnatVd (gcc) 12967 12968 12969@table @asis 12970 12971@item @code{-gnatVd} 12972 12973@emph{Default (RM) validity checks.} 12974 12975Some validity checks are done by default following normal Ada semantics 12976(RM 13.9.1 (9-11)). 12977A check is done in case statements that the expression is within the range 12978of the subtype. If it is not, Constraint_Error is raised. 12979For assignments to array components, a check is done that the expression used 12980as index is within the range. If it is not, Constraint_Error is raised. 12981Both these validity checks may be turned off using switch @code{-gnatVD}. 12982They are turned on by default. If @code{-gnatVD} is specified, a subsequent 12983switch @code{-gnatVd} will leave the checks turned on. 12984Switch @code{-gnatVD} should be used only if you are sure that all such 12985expressions have valid values. If you use this switch and invalid values 12986are present, then the program is erroneous, and wild jumps or memory 12987overwriting may occur. 12988@end table 12989 12990@geindex -gnatVe (gcc) 12991 12992 12993@table @asis 12994 12995@item @code{-gnatVe} 12996 12997@emph{Validity checks for elementary components.} 12998 12999In the absence of this switch, assignments to record or array components are 13000not validity checked, even if validity checks for assignments generally 13001(@code{-gnatVc}) are turned on. In Ada, assignment of composite values do not 13002require valid data, but assignment of individual components does. So for 13003example, there is a difference between copying the elements of an array with a 13004slice assignment, compared to assigning element by element in a loop. This 13005switch allows you to turn off validity checking for components, even when they 13006are assigned component by component. 13007@end table 13008 13009@geindex -gnatVf (gcc) 13010 13011 13012@table @asis 13013 13014@item @code{-gnatVf} 13015 13016@emph{Validity checks for floating-point values.} 13017 13018In the absence of this switch, validity checking occurs only for discrete 13019values. If @code{-gnatVf} is specified, then validity checking also applies 13020for floating-point values, and NaNs and infinities are considered invalid, 13021as well as out of range values for constrained types. Note that this means 13022that standard IEEE infinity mode is not allowed. The exact contexts 13023in which floating-point values are checked depends on the setting of other 13024options. For example, @code{-gnatVif} or @code{-gnatVfi} 13025(the order does not matter) specifies that floating-point parameters of mode 13026@code{in} should be validity checked. 13027@end table 13028 13029@geindex -gnatVi (gcc) 13030 13031 13032@table @asis 13033 13034@item @code{-gnatVi} 13035 13036@emph{Validity checks for `@w{`}in`@w{`} mode parameters.} 13037 13038Arguments for parameters of mode @code{in} are validity checked in function 13039and procedure calls at the point of call. 13040@end table 13041 13042@geindex -gnatVm (gcc) 13043 13044 13045@table @asis 13046 13047@item @code{-gnatVm} 13048 13049@emph{Validity checks for `@w{`}in out`@w{`} mode parameters.} 13050 13051Arguments for parameters of mode @code{in out} are validity checked in 13052procedure calls at the point of call. The @code{'m'} here stands for 13053modify, since this concerns parameters that can be modified by the call. 13054Note that there is no specific option to test @code{out} parameters, 13055but any reference within the subprogram will be tested in the usual 13056manner, and if an invalid value is copied back, any reference to it 13057will be subject to validity checking. 13058@end table 13059 13060@geindex -gnatVn (gcc) 13061 13062 13063@table @asis 13064 13065@item @code{-gnatVn} 13066 13067@emph{No validity checks.} 13068 13069This switch turns off all validity checking, including the default checking 13070for case statements and left hand side subscripts. Note that the use of 13071the switch @code{-gnatp} suppresses all run-time checks, including 13072validity checks, and thus implies @code{-gnatVn}. When this switch 13073is used, it cancels any other @code{-gnatV} previously issued. 13074@end table 13075 13076@geindex -gnatVo (gcc) 13077 13078 13079@table @asis 13080 13081@item @code{-gnatVo} 13082 13083@emph{Validity checks for operator and attribute operands.} 13084 13085Arguments for predefined operators and attributes are validity checked. 13086This includes all operators in package @code{Standard}, 13087the shift operators defined as intrinsic in package @code{Interfaces} 13088and operands for attributes such as @code{Pos}. Checks are also made 13089on individual component values for composite comparisons, and on the 13090expressions in type conversions and qualified expressions. Checks are 13091also made on explicit ranges using @code{..} (e.g., slices, loops etc). 13092@end table 13093 13094@geindex -gnatVp (gcc) 13095 13096 13097@table @asis 13098 13099@item @code{-gnatVp} 13100 13101@emph{Validity checks for parameters.} 13102 13103This controls the treatment of parameters within a subprogram (as opposed 13104to @code{-gnatVi} and @code{-gnatVm} which control validity testing 13105of parameters on a call. If either of these call options is used, then 13106normally an assumption is made within a subprogram that the input arguments 13107have been validity checking at the point of call, and do not need checking 13108again within a subprogram). If @code{-gnatVp} is set, then this assumption 13109is not made, and parameters are not assumed to be valid, so their validity 13110will be checked (or rechecked) within the subprogram. 13111@end table 13112 13113@geindex -gnatVr (gcc) 13114 13115 13116@table @asis 13117 13118@item @code{-gnatVr} 13119 13120@emph{Validity checks for function returns.} 13121 13122The expression in @code{return} statements in functions is validity 13123checked. 13124@end table 13125 13126@geindex -gnatVs (gcc) 13127 13128 13129@table @asis 13130 13131@item @code{-gnatVs} 13132 13133@emph{Validity checks for subscripts.} 13134 13135All subscripts expressions are checked for validity, whether they appear 13136on the right side or left side (in default mode only left side subscripts 13137are validity checked). 13138@end table 13139 13140@geindex -gnatVt (gcc) 13141 13142 13143@table @asis 13144 13145@item @code{-gnatVt} 13146 13147@emph{Validity checks for tests.} 13148 13149Expressions used as conditions in @code{if}, @code{while} or @code{exit} 13150statements are checked, as well as guard expressions in entry calls. 13151@end table 13152 13153The @code{-gnatV} switch may be followed by a string of letters 13154to turn on a series of validity checking options. 13155For example, @code{-gnatVcr} 13156specifies that in addition to the default validity checking, copies and 13157function return expressions are to be validity checked. 13158In order to make it easier to specify the desired combination of effects, 13159the upper case letters @code{CDFIMORST} may 13160be used to turn off the corresponding lower case option. 13161Thus @code{-gnatVaM} turns on all validity checking options except for 13162checking of @code{in out} parameters. 13163 13164The specification of additional validity checking generates extra code (and 13165in the case of @code{-gnatVa} the code expansion can be substantial). 13166However, these additional checks can be very useful in detecting 13167uninitialized variables, incorrect use of unchecked conversion, and other 13168errors leading to invalid values. The use of pragma @code{Initialize_Scalars} 13169is useful in conjunction with the extra validity checking, since this 13170ensures that wherever possible uninitialized variables have invalid values. 13171 13172See also the pragma @code{Validity_Checks} which allows modification of 13173the validity checking mode at the program source level, and also allows for 13174temporary disabling of validity checks. 13175 13176@node Style Checking,Run-Time Checks,Validity Checking,Compiler Switches 13177@anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{f4}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{ec} 13178@subsection Style Checking 13179 13180 13181@geindex Style checking 13182 13183@geindex -gnaty (gcc) 13184 13185The @code{-gnatyx} switch causes the compiler to 13186enforce specified style rules. A limited set of style rules has been used 13187in writing the GNAT sources themselves. This switch allows user programs 13188to activate all or some of these checks. If the source program fails a 13189specified style check, an appropriate message is given, preceded by 13190the character sequence '(style)'. This message does not prevent 13191successful compilation (unless the @code{-gnatwe} switch is used). 13192 13193Note that this is by no means intended to be a general facility for 13194checking arbitrary coding standards. It is simply an embedding of the 13195style rules we have chosen for the GNAT sources. If you are starting 13196a project which does not have established style standards, you may 13197find it useful to adopt the entire set of GNAT coding standards, or 13198some subset of them. 13199 13200 13201The string @code{x} is a sequence of letters or digits 13202indicating the particular style 13203checks to be performed. The following checks are defined: 13204 13205@geindex -gnaty[0-9] (gcc) 13206 13207 13208@table @asis 13209 13210@item @code{-gnaty0} 13211 13212@emph{Specify indentation level.} 13213 13214If a digit from 1-9 appears 13215in the string after @code{-gnaty} 13216then proper indentation is checked, with the digit indicating the 13217indentation level required. A value of zero turns off this style check. 13218The general style of required indentation is as specified by 13219the examples in the Ada Reference Manual. Full line comments must be 13220aligned with the @code{--} starting on a column that is a multiple of 13221the alignment level, or they may be aligned the same way as the following 13222non-blank line (this is useful when full line comments appear in the middle 13223of a statement, or they may be aligned with the source line on the previous 13224non-blank line. 13225@end table 13226 13227@geindex -gnatya (gcc) 13228 13229 13230@table @asis 13231 13232@item @code{-gnatya} 13233 13234@emph{Check attribute casing.} 13235 13236Attribute names, including the case of keywords such as @code{digits} 13237used as attributes names, must be written in mixed case, that is, the 13238initial letter and any letter following an underscore must be uppercase. 13239All other letters must be lowercase. 13240@end table 13241 13242@geindex -gnatyA (gcc) 13243 13244 13245@table @asis 13246 13247@item @code{-gnatyA} 13248 13249@emph{Use of array index numbers in array attributes.} 13250 13251When using the array attributes First, Last, Range, 13252or Length, the index number must be omitted for one-dimensional arrays 13253and is required for multi-dimensional arrays. 13254@end table 13255 13256@geindex -gnatyb (gcc) 13257 13258 13259@table @asis 13260 13261@item @code{-gnatyb} 13262 13263@emph{Blanks not allowed at statement end.} 13264 13265Trailing blanks are not allowed at the end of statements. The purpose of this 13266rule, together with h (no horizontal tabs), is to enforce a canonical format 13267for the use of blanks to separate source tokens. 13268@end table 13269 13270@geindex -gnatyB (gcc) 13271 13272 13273@table @asis 13274 13275@item @code{-gnatyB} 13276 13277@emph{Check Boolean operators.} 13278 13279The use of AND/OR operators is not permitted except in the cases of modular 13280operands, array operands, and simple stand-alone boolean variables or 13281boolean constants. In all other cases @code{and then}/@cite{or else} are 13282required. 13283@end table 13284 13285@geindex -gnatyc (gcc) 13286 13287 13288@table @asis 13289 13290@item @code{-gnatyc} 13291 13292@emph{Check comments, double space.} 13293 13294Comments must meet the following set of rules: 13295 13296 13297@itemize * 13298 13299@item 13300The @code{--} that starts the column must either start in column one, 13301or else at least one blank must precede this sequence. 13302 13303@item 13304Comments that follow other tokens on a line must have at least one blank 13305following the @code{--} at the start of the comment. 13306 13307@item 13308Full line comments must have at least two blanks following the 13309@code{--} that starts the comment, with the following exceptions. 13310 13311@item 13312A line consisting only of the @code{--} characters, possibly preceded 13313by blanks is permitted. 13314 13315@item 13316A comment starting with @code{--x} where @code{x} is a special character 13317is permitted. 13318This allows proper processing of the output from specialized tools 13319such as @code{gnatprep} (where @code{--!} is used) and in earlier versions of the SPARK 13320annotation 13321language (where @code{--#} is used). For the purposes of this rule, a 13322special character is defined as being in one of the ASCII ranges 13323@code{16#21#...16#2F#} or @code{16#3A#...16#3F#}. 13324Note that this usage is not permitted 13325in GNAT implementation units (i.e., when @code{-gnatg} is used). 13326 13327@item 13328A line consisting entirely of minus signs, possibly preceded by blanks, is 13329permitted. This allows the construction of box comments where lines of minus 13330signs are used to form the top and bottom of the box. 13331 13332@item 13333A comment that starts and ends with @code{--} is permitted as long as at 13334least one blank follows the initial @code{--}. Together with the preceding 13335rule, this allows the construction of box comments, as shown in the following 13336example: 13337 13338@example 13339--------------------------- 13340-- This is a box comment -- 13341-- with two text lines. -- 13342--------------------------- 13343@end example 13344@end itemize 13345@end table 13346 13347@geindex -gnatyC (gcc) 13348 13349 13350@table @asis 13351 13352@item @code{-gnatyC} 13353 13354@emph{Check comments, single space.} 13355 13356This is identical to @code{c} except that only one space 13357is required following the @code{--} of a comment instead of two. 13358@end table 13359 13360@geindex -gnatyd (gcc) 13361 13362 13363@table @asis 13364 13365@item @code{-gnatyd} 13366 13367@emph{Check no DOS line terminators present.} 13368 13369All lines must be terminated by a single ASCII.LF 13370character (in particular the DOS line terminator sequence CR/LF is not 13371allowed). 13372@end table 13373 13374@geindex -gnatyD (gcc) 13375 13376 13377@table @asis 13378 13379@item @code{-gnatyD} 13380 13381@emph{Check declared identifiers in mixed case.} 13382 13383Declared identifiers must be in mixed case, as in 13384This_Is_An_Identifier. Use -gnatyr in addition to ensure 13385that references match declarations. 13386@end table 13387 13388@geindex -gnatye (gcc) 13389 13390 13391@table @asis 13392 13393@item @code{-gnatye} 13394 13395@emph{Check end/exit labels.} 13396 13397Optional labels on @code{end} statements ending subprograms and on 13398@code{exit} statements exiting named loops, are required to be present. 13399@end table 13400 13401@geindex -gnatyf (gcc) 13402 13403 13404@table @asis 13405 13406@item @code{-gnatyf} 13407 13408@emph{No form feeds or vertical tabs.} 13409 13410Neither form feeds nor vertical tab characters are permitted 13411in the source text. 13412@end table 13413 13414@geindex -gnatyg (gcc) 13415 13416 13417@table @asis 13418 13419@item @code{-gnatyg} 13420 13421@emph{GNAT style mode.} 13422 13423The set of style check switches is set to match that used by the GNAT sources. 13424This may be useful when developing code that is eventually intended to be 13425incorporated into GNAT. Currently this is equivalent to @code{-gnatyydISux}) 13426but additional style switches may be added to this set in the future without 13427advance notice. 13428@end table 13429 13430@geindex -gnatyh (gcc) 13431 13432 13433@table @asis 13434 13435@item @code{-gnatyh} 13436 13437@emph{No horizontal tabs.} 13438 13439Horizontal tab characters are not permitted in the source text. 13440Together with the b (no blanks at end of line) check, this 13441enforces a canonical form for the use of blanks to separate 13442source tokens. 13443@end table 13444 13445@geindex -gnatyi (gcc) 13446 13447 13448@table @asis 13449 13450@item @code{-gnatyi} 13451 13452@emph{Check if-then layout.} 13453 13454The keyword @code{then} must appear either on the same 13455line as corresponding @code{if}, or on a line on its own, lined 13456up under the @code{if}. 13457@end table 13458 13459@geindex -gnatyI (gcc) 13460 13461 13462@table @asis 13463 13464@item @code{-gnatyI} 13465 13466@emph{check mode IN keywords.} 13467 13468Mode @code{in} (the default mode) is not 13469allowed to be given explicitly. @code{in out} is fine, 13470but not @code{in} on its own. 13471@end table 13472 13473@geindex -gnatyk (gcc) 13474 13475 13476@table @asis 13477 13478@item @code{-gnatyk} 13479 13480@emph{Check keyword casing.} 13481 13482All keywords must be in lower case (with the exception of keywords 13483such as @code{digits} used as attribute names to which this check 13484does not apply). A single error is reported for each line breaking 13485this rule even if multiple casing issues exist on a same line. 13486@end table 13487 13488@geindex -gnatyl (gcc) 13489 13490 13491@table @asis 13492 13493@item @code{-gnatyl} 13494 13495@emph{Check layout.} 13496 13497Layout of statement and declaration constructs must follow the 13498recommendations in the Ada Reference Manual, as indicated by the 13499form of the syntax rules. For example an @code{else} keyword must 13500be lined up with the corresponding @code{if} keyword. 13501 13502There are two respects in which the style rule enforced by this check 13503option are more liberal than those in the Ada Reference Manual. First 13504in the case of record declarations, it is permissible to put the 13505@code{record} keyword on the same line as the @code{type} keyword, and 13506then the @code{end} in @code{end record} must line up under @code{type}. 13507This is also permitted when the type declaration is split on two lines. 13508For example, any of the following three layouts is acceptable: 13509 13510@example 13511type q is record 13512 a : integer; 13513 b : integer; 13514end record; 13515 13516type q is 13517 record 13518 a : integer; 13519 b : integer; 13520 end record; 13521 13522type q is 13523 record 13524 a : integer; 13525 b : integer; 13526end record; 13527@end example 13528 13529Second, in the case of a block statement, a permitted alternative 13530is to put the block label on the same line as the @code{declare} or 13531@code{begin} keyword, and then line the @code{end} keyword up under 13532the block label. For example both the following are permitted: 13533 13534@example 13535Block : declare 13536 A : Integer := 3; 13537begin 13538 Proc (A, A); 13539end Block; 13540 13541Block : 13542 declare 13543 A : Integer := 3; 13544 begin 13545 Proc (A, A); 13546 end Block; 13547@end example 13548 13549The same alternative format is allowed for loops. For example, both of 13550the following are permitted: 13551 13552@example 13553Clear : while J < 10 loop 13554 A (J) := 0; 13555end loop Clear; 13556 13557Clear : 13558 while J < 10 loop 13559 A (J) := 0; 13560 end loop Clear; 13561@end example 13562@end table 13563 13564@geindex -gnatyLnnn (gcc) 13565 13566 13567@table @asis 13568 13569@item @code{-gnatyL} 13570 13571@emph{Set maximum nesting level.} 13572 13573The maximum level of nesting of constructs (including subprograms, loops, 13574blocks, packages, and conditionals) may not exceed the given value 13575@emph{nnn}. A value of zero disconnects this style check. 13576@end table 13577 13578@geindex -gnatym (gcc) 13579 13580 13581@table @asis 13582 13583@item @code{-gnatym} 13584 13585@emph{Check maximum line length.} 13586 13587The length of source lines must not exceed 79 characters, including 13588any trailing blanks. The value of 79 allows convenient display on an 1358980 character wide device or window, allowing for possible special 13590treatment of 80 character lines. Note that this count is of 13591characters in the source text. This means that a tab character counts 13592as one character in this count and a wide character sequence counts as 13593a single character (however many bytes are needed in the encoding). 13594@end table 13595 13596@geindex -gnatyMnnn (gcc) 13597 13598 13599@table @asis 13600 13601@item @code{-gnatyM} 13602 13603@emph{Set maximum line length.} 13604 13605The length of lines must not exceed the 13606given value @emph{nnn}. The maximum value that can be specified is 32767. 13607If neither style option for setting the line length is used, then the 13608default is 255. This also controls the maximum length of lexical elements, 13609where the only restriction is that they must fit on a single line. 13610@end table 13611 13612@geindex -gnatyn (gcc) 13613 13614 13615@table @asis 13616 13617@item @code{-gnatyn} 13618 13619@emph{Check casing of entities in Standard.} 13620 13621Any identifier from Standard must be cased 13622to match the presentation in the Ada Reference Manual (for example, 13623@code{Integer} and @code{ASCII.NUL}). 13624@end table 13625 13626@geindex -gnatyN (gcc) 13627 13628 13629@table @asis 13630 13631@item @code{-gnatyN} 13632 13633@emph{Turn off all style checks.} 13634 13635All style check options are turned off. 13636@end table 13637 13638@geindex -gnatyo (gcc) 13639 13640 13641@table @asis 13642 13643@item @code{-gnatyo} 13644 13645@emph{Check order of subprogram bodies.} 13646 13647All subprogram bodies in a given scope 13648(e.g., a package body) must be in alphabetical order. The ordering 13649rule uses normal Ada rules for comparing strings, ignoring casing 13650of letters, except that if there is a trailing numeric suffix, then 13651the value of this suffix is used in the ordering (e.g., Junk2 comes 13652before Junk10). 13653@end table 13654 13655@geindex -gnatyO (gcc) 13656 13657 13658@table @asis 13659 13660@item @code{-gnatyO} 13661 13662@emph{Check that overriding subprograms are explicitly marked as such.} 13663 13664This applies to all subprograms of a derived type that override a primitive 13665operation of the type, for both tagged and untagged types. In particular, 13666the declaration of a primitive operation of a type extension that overrides 13667an inherited operation must carry an overriding indicator. Another case is 13668the declaration of a function that overrides a predefined operator (such 13669as an equality operator). 13670@end table 13671 13672@geindex -gnatyp (gcc) 13673 13674 13675@table @asis 13676 13677@item @code{-gnatyp} 13678 13679@emph{Check pragma casing.} 13680 13681Pragma names must be written in mixed case, that is, the 13682initial letter and any letter following an underscore must be uppercase. 13683All other letters must be lowercase. An exception is that SPARK_Mode is 13684allowed as an alternative for Spark_Mode. 13685@end table 13686 13687@geindex -gnatyr (gcc) 13688 13689 13690@table @asis 13691 13692@item @code{-gnatyr} 13693 13694@emph{Check references.} 13695 13696All identifier references must be cased in the same way as the 13697corresponding declaration. No specific casing style is imposed on 13698identifiers. The only requirement is for consistency of references 13699with declarations. 13700@end table 13701 13702@geindex -gnatys (gcc) 13703 13704 13705@table @asis 13706 13707@item @code{-gnatys} 13708 13709@emph{Check separate specs.} 13710 13711Separate declarations ('specs') are required for subprograms (a 13712body is not allowed to serve as its own declaration). The only 13713exception is that parameterless library level procedures are 13714not required to have a separate declaration. This exception covers 13715the most frequent form of main program procedures. 13716@end table 13717 13718@geindex -gnatyS (gcc) 13719 13720 13721@table @asis 13722 13723@item @code{-gnatyS} 13724 13725@emph{Check no statements after then/else.} 13726 13727No statements are allowed 13728on the same line as a @code{then} or @code{else} keyword following the 13729keyword in an @code{if} statement. @code{or else} and @code{and then} are not 13730affected, and a special exception allows a pragma to appear after @code{else}. 13731@end table 13732 13733@geindex -gnatyt (gcc) 13734 13735 13736@table @asis 13737 13738@item @code{-gnatyt} 13739 13740@emph{Check token spacing.} 13741 13742The following token spacing rules are enforced: 13743 13744 13745@itemize * 13746 13747@item 13748The keywords @code{abs} and @code{not} must be followed by a space. 13749 13750@item 13751The token @code{=>} must be surrounded by spaces. 13752 13753@item 13754The token @code{<>} must be preceded by a space or a left parenthesis. 13755 13756@item 13757Binary operators other than @code{**} must be surrounded by spaces. 13758There is no restriction on the layout of the @code{**} binary operator. 13759 13760@item 13761Colon must be surrounded by spaces. 13762 13763@item 13764Colon-equal (assignment, initialization) must be surrounded by spaces. 13765 13766@item 13767Comma must be the first non-blank character on the line, or be 13768immediately preceded by a non-blank character, and must be followed 13769by a space. 13770 13771@item 13772If the token preceding a left parenthesis ends with a letter or digit, then 13773a space must separate the two tokens. 13774 13775@item 13776If the token following a right parenthesis starts with a letter or digit, then 13777a space must separate the two tokens. 13778 13779@item 13780A right parenthesis must either be the first non-blank character on 13781a line, or it must be preceded by a non-blank character. 13782 13783@item 13784A semicolon must not be preceded by a space, and must not be followed by 13785a non-blank character. 13786 13787@item 13788A unary plus or minus may not be followed by a space. 13789 13790@item 13791A vertical bar must be surrounded by spaces. 13792@end itemize 13793 13794Exactly one blank (and no other white space) must appear between 13795a @code{not} token and a following @code{in} token. 13796@end table 13797 13798@geindex -gnatyu (gcc) 13799 13800 13801@table @asis 13802 13803@item @code{-gnatyu} 13804 13805@emph{Check unnecessary blank lines.} 13806 13807Unnecessary blank lines are not allowed. A blank line is considered 13808unnecessary if it appears at the end of the file, or if more than 13809one blank line occurs in sequence. 13810@end table 13811 13812@geindex -gnatyx (gcc) 13813 13814 13815@table @asis 13816 13817@item @code{-gnatyx} 13818 13819@emph{Check extra parentheses.} 13820 13821Unnecessary extra level of parentheses (C-style) are not allowed 13822around conditions in @code{if} statements, @code{while} statements and 13823@code{exit} statements. 13824@end table 13825 13826@geindex -gnatyy (gcc) 13827 13828 13829@table @asis 13830 13831@item @code{-gnatyy} 13832 13833@emph{Set all standard style check options.} 13834 13835This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking 13836options enabled with the exception of @code{-gnatyB}, @code{-gnatyd}, 13837@code{-gnatyI}, @code{-gnatyLnnn}, @code{-gnatyo}, @code{-gnatyO}, 13838@code{-gnatyS}, @code{-gnatyu}, and @code{-gnatyx}. 13839@end table 13840 13841@geindex -gnaty- (gcc) 13842 13843 13844@table @asis 13845 13846@item @code{-gnaty-} 13847 13848@emph{Remove style check options.} 13849 13850This causes any subsequent options in the string to act as canceling the 13851corresponding style check option. To cancel maximum nesting level control, 13852use the @code{L} parameter without any integer value after that, because any 13853digit following @emph{-} in the parameter string of the @code{-gnaty} 13854option will be treated as canceling the indentation check. The same is true 13855for the @code{M} parameter. @code{y} and @code{N} parameters are not 13856allowed after @emph{-}. 13857@end table 13858 13859@geindex -gnaty+ (gcc) 13860 13861 13862@table @asis 13863 13864@item @code{-gnaty+} 13865 13866@emph{Enable style check options.} 13867 13868This causes any subsequent options in the string to enable the corresponding 13869style check option. That is, it cancels the effect of a previous -, 13870if any. 13871@end table 13872 13873@c end of switch description (leave this comment to ease automatic parsing for 13874 13875@c GNAT Studio 13876 13877In the above rules, appearing in column one is always permitted, that is, 13878counts as meeting either a requirement for a required preceding space, 13879or as meeting a requirement for no preceding space. 13880 13881Appearing at the end of a line is also always permitted, that is, counts 13882as meeting either a requirement for a following space, or as meeting 13883a requirement for no following space. 13884 13885If any of these style rules is violated, a message is generated giving 13886details on the violation. The initial characters of such messages are 13887always '@cite{(style)}'. Note that these messages are treated as warning 13888messages, so they normally do not prevent the generation of an object 13889file. The @code{-gnatwe} switch can be used to treat warning messages, 13890including style messages, as fatal errors. 13891 13892The switch @code{-gnaty} on its own (that is not 13893followed by any letters or digits) is equivalent 13894to the use of @code{-gnatyy} as described above, that is all 13895built-in standard style check options are enabled. 13896 13897The switch @code{-gnatyN} clears any previously set style checks. 13898 13899@node Run-Time Checks,Using gcc for Syntax Checking,Style Checking,Compiler Switches 13900@anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{ea}@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{f5} 13901@subsection Run-Time Checks 13902 13903 13904@geindex Division by zero 13905 13906@geindex Access before elaboration 13907 13908@geindex Checks 13909@geindex division by zero 13910 13911@geindex Checks 13912@geindex access before elaboration 13913 13914@geindex Checks 13915@geindex stack overflow checking 13916 13917By default, the following checks are suppressed: stack overflow 13918checks, and checks for access before elaboration on subprogram 13919calls. All other checks, including overflow checks, range checks and 13920array bounds checks, are turned on by default. The following @code{gcc} 13921switches refine this default behavior. 13922 13923@geindex -gnatp (gcc) 13924 13925 13926@table @asis 13927 13928@item @code{-gnatp} 13929 13930@geindex Suppressing checks 13931 13932@geindex Checks 13933@geindex suppressing 13934 13935This switch causes the unit to be compiled 13936as though @code{pragma Suppress (All_checks)} 13937had been present in the source. Validity checks are also eliminated (in 13938other words @code{-gnatp} also implies @code{-gnatVn}. 13939Use this switch to improve the performance 13940of the code at the expense of safety in the presence of invalid data or 13941program bugs. 13942 13943Note that when checks are suppressed, the compiler is allowed, but not 13944required, to omit the checking code. If the run-time cost of the 13945checking code is zero or near-zero, the compiler will generate it even 13946if checks are suppressed. In particular, if the compiler can prove 13947that a certain check will necessarily fail, it will generate code to 13948do an unconditional 'raise', even if checks are suppressed. The 13949compiler warns in this case. Another case in which checks may not be 13950eliminated is when they are embedded in certain run-time routines such 13951as math library routines. 13952 13953Of course, run-time checks are omitted whenever the compiler can prove 13954that they will not fail, whether or not checks are suppressed. 13955 13956Note that if you suppress a check that would have failed, program 13957execution is erroneous, which means the behavior is totally 13958unpredictable. The program might crash, or print wrong answers, or 13959do anything else. It might even do exactly what you wanted it to do 13960(and then it might start failing mysteriously next week or next 13961year). The compiler will generate code based on the assumption that 13962the condition being checked is true, which can result in erroneous 13963execution if that assumption is wrong. 13964 13965The checks subject to suppression include all the checks defined by the Ada 13966standard, the additional implementation defined checks @code{Alignment_Check}, 13967@code{Duplicated_Tag_Check}, @code{Predicate_Check}, @code{Container_Checks}, @code{Tampering_Check}, 13968and @code{Validity_Check}, as well as any checks introduced using @code{pragma Check_Name}. 13969Note that @code{Atomic_Synchronization} is not automatically suppressed by use of this option. 13970 13971If the code depends on certain checks being active, you can use 13972pragma @code{Unsuppress} either as a configuration pragma or as 13973a local pragma to make sure that a specified check is performed 13974even if @code{gnatp} is specified. 13975 13976The @code{-gnatp} switch has no effect if a subsequent 13977@code{-gnat-p} switch appears. 13978@end table 13979 13980@geindex -gnat-p (gcc) 13981 13982@geindex Suppressing checks 13983 13984@geindex Checks 13985@geindex suppressing 13986 13987@geindex Suppress 13988 13989 13990@table @asis 13991 13992@item @code{-gnat-p} 13993 13994This switch cancels the effect of a previous @code{gnatp} switch. 13995@end table 13996 13997@geindex -gnato?? (gcc) 13998 13999@geindex Overflow checks 14000 14001@geindex Overflow mode 14002 14003@geindex Check 14004@geindex overflow 14005 14006 14007@table @asis 14008 14009@item @code{-gnato??} 14010 14011This switch controls the mode used for computing intermediate 14012arithmetic integer operations, and also enables overflow checking. 14013For a full description of overflow mode and checking control, see 14014the 'Overflow Check Handling in GNAT' appendix in this 14015User's Guide. 14016 14017Overflow checks are always enabled by this switch. The argument 14018controls the mode, using the codes 14019 14020 14021@table @asis 14022 14023@item @emph{1 = STRICT} 14024 14025In STRICT mode, intermediate operations are always done using the 14026base type, and overflow checking ensures that the result is within 14027the base type range. 14028 14029@item @emph{2 = MINIMIZED} 14030 14031In MINIMIZED mode, overflows in intermediate operations are avoided 14032where possible by using a larger integer type for the computation 14033(typically @code{Long_Long_Integer}). Overflow checking ensures that 14034the result fits in this larger integer type. 14035 14036@item @emph{3 = ELIMINATED} 14037 14038In ELIMINATED mode, overflows in intermediate operations are avoided 14039by using multi-precision arithmetic. In this case, overflow checking 14040has no effect on intermediate operations (since overflow is impossible). 14041@end table 14042 14043If two digits are present after @code{-gnato} then the first digit 14044sets the mode for expressions outside assertions, and the second digit 14045sets the mode for expressions within assertions. Here assertions is used 14046in the technical sense (which includes for example precondition and 14047postcondition expressions). 14048 14049If one digit is present, the corresponding mode is applicable to both 14050expressions within and outside assertion expressions. 14051 14052If no digits are present, the default is to enable overflow checks 14053and set STRICT mode for both kinds of expressions. This is compatible 14054with the use of @code{-gnato} in previous versions of GNAT. 14055 14056@geindex Machine_Overflows 14057 14058Note that the @code{-gnato??} switch does not affect the code generated 14059for any floating-point operations; it applies only to integer semantics. 14060For floating-point, GNAT has the @code{Machine_Overflows} 14061attribute set to @code{False} and the normal mode of operation is to 14062generate IEEE NaN and infinite values on overflow or invalid operations 14063(such as dividing 0.0 by 0.0). 14064 14065The reason that we distinguish overflow checking from other kinds of 14066range constraint checking is that a failure of an overflow check, unlike 14067for example the failure of a range check, can result in an incorrect 14068value, but cannot cause random memory destruction (like an out of range 14069subscript), or a wild jump (from an out of range case value). Overflow 14070checking is also quite expensive in time and space, since in general it 14071requires the use of double length arithmetic. 14072 14073Note again that the default is @code{-gnato11} (equivalent to @code{-gnato1}), 14074so overflow checking is performed in STRICT mode by default. 14075@end table 14076 14077@geindex -gnatE (gcc) 14078 14079@geindex Elaboration checks 14080 14081@geindex Check 14082@geindex elaboration 14083 14084 14085@table @asis 14086 14087@item @code{-gnatE} 14088 14089Enables dynamic checks for access-before-elaboration 14090on subprogram calls and generic instantiations. 14091Note that @code{-gnatE} is not necessary for safety, because in the 14092default mode, GNAT ensures statically that the checks would not fail. 14093For full details of the effect and use of this switch, 14094@ref{c7,,Compiling with gcc}. 14095@end table 14096 14097@geindex -fstack-check (gcc) 14098 14099@geindex Stack Overflow Checking 14100 14101@geindex Checks 14102@geindex stack overflow checking 14103 14104 14105@table @asis 14106 14107@item @code{-fstack-check} 14108 14109Activates stack overflow checking. For full details of the effect and use of 14110this switch see @ref{e5,,Stack Overflow Checking}. 14111@end table 14112 14113@geindex Unsuppress 14114 14115The setting of these switches only controls the default setting of the 14116checks. You may modify them using either @code{Suppress} (to remove 14117checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in 14118the program source. 14119 14120@node Using gcc for Syntax Checking,Using gcc for Semantic Checking,Run-Time Checks,Compiler Switches 14121@anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{f7} 14122@subsection Using @code{gcc} for Syntax Checking 14123 14124 14125@geindex -gnats (gcc) 14126 14127 14128@table @asis 14129 14130@item @code{-gnats} 14131 14132The @code{s} stands for 'syntax'. 14133 14134Run GNAT in syntax checking only mode. For 14135example, the command 14136 14137@example 14138$ gcc -c -gnats x.adb 14139@end example 14140 14141compiles file @code{x.adb} in syntax-check-only mode. You can check a 14142series of files in a single command 14143, and can use wildcards to specify such a group of files. 14144Note that you must specify the @code{-c} (compile 14145only) flag in addition to the @code{-gnats} flag. 14146 14147You may use other switches in conjunction with @code{-gnats}. In 14148particular, @code{-gnatl} and @code{-gnatv} are useful to control the 14149format of any generated error messages. 14150 14151When the source file is empty or contains only empty lines and/or comments, 14152the output is a warning: 14153 14154@example 14155$ gcc -c -gnats -x ada toto.txt 14156toto.txt:1:01: warning: empty file, contains no compilation units 14157$ 14158@end example 14159 14160Otherwise, the output is simply the error messages, if any. No object file or 14161ALI file is generated by a syntax-only compilation. Also, no units other 14162than the one specified are accessed. For example, if a unit @code{X} 14163@emph{with}s a unit @code{Y}, compiling unit @code{X} in syntax 14164check only mode does not access the source file containing unit 14165@code{Y}. 14166 14167@geindex Multiple units 14168@geindex syntax checking 14169 14170Normally, GNAT allows only a single unit in a source file. However, this 14171restriction does not apply in syntax-check-only mode, and it is possible 14172to check a file containing multiple compilation units concatenated 14173together. This is primarily used by the @code{gnatchop} utility 14174(@ref{1d,,Renaming Files with gnatchop}). 14175@end table 14176 14177@node Using gcc for Semantic Checking,Compiling Different Versions of Ada,Using gcc for Syntax Checking,Compiler Switches 14178@anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{f8}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{f9} 14179@subsection Using @code{gcc} for Semantic Checking 14180 14181 14182@geindex -gnatc (gcc) 14183 14184 14185@table @asis 14186 14187@item @code{-gnatc} 14188 14189The @code{c} stands for 'check'. 14190Causes the compiler to operate in semantic check mode, 14191with full checking for all illegalities specified in the 14192Ada Reference Manual, but without generation of any object code 14193(no object file is generated). 14194 14195Because dependent files must be accessed, you must follow the GNAT 14196semantic restrictions on file structuring to operate in this mode: 14197 14198 14199@itemize * 14200 14201@item 14202The needed source files must be accessible 14203(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). 14204 14205@item 14206Each file must contain only one compilation unit. 14207 14208@item 14209The file name and unit name must match (@ref{3b,,File Naming Rules}). 14210@end itemize 14211 14212The output consists of error messages as appropriate. No object file is 14213generated. An @code{ALI} file is generated for use in the context of 14214cross-reference tools, but this file is marked as not being suitable 14215for binding (since no object file is generated). 14216The checking corresponds exactly to the notion of 14217legality in the Ada Reference Manual. 14218 14219Any unit can be compiled in semantics-checking-only mode, including 14220units that would not normally be compiled (subunits, 14221and specifications where a separate body is present). 14222@end table 14223 14224@node Compiling Different Versions of Ada,Character Set Control,Using gcc for Semantic Checking,Compiler Switches 14225@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{fa} 14226@subsection Compiling Different Versions of Ada 14227 14228 14229The switches described in this section allow you to explicitly specify 14230the version of the Ada language that your programs are written in. 14231The default mode is Ada 2012, 14232but you can also specify Ada 95, Ada 2005 mode, or 14233indicate Ada 83 compatibility mode. 14234 14235@geindex Compatibility with Ada 83 14236 14237@geindex -gnat83 (gcc) 14238 14239@geindex ACVC 14240@geindex Ada 83 tests 14241 14242@geindex Ada 83 mode 14243 14244 14245@table @asis 14246 14247@item @code{-gnat83} (Ada 83 Compatibility Mode) 14248 14249Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch 14250specifies that the program is to be compiled in Ada 83 mode. With 14251@code{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83 14252semantics where this can be done easily. 14253It is not possible to guarantee this switch does a perfect 14254job; some subtle tests, such as are 14255found in earlier ACVC tests (and that have been removed from the ACATS suite 14256for Ada 95), might not compile correctly. 14257Nevertheless, this switch may be useful in some circumstances, for example 14258where, due to contractual reasons, existing code needs to be maintained 14259using only Ada 83 features. 14260 14261With few exceptions (most notably the need to use @code{<>} on 14262unconstrained 14263@geindex Generic formal parameters 14264generic formal parameters, 14265the use of the new Ada 95 / Ada 2005 14266reserved words, and the use of packages 14267with optional bodies), it is not necessary to specify the 14268@code{-gnat83} switch when compiling Ada 83 programs, because, with rare 14269exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus 14270a correct Ada 83 program is usually also a correct program 14271in these later versions of the language standard. For further information 14272please refer to the @emph{Compatibility and Porting Guide} chapter in the 14273@cite{GNAT Reference Manual}. 14274@end table 14275 14276@geindex -gnat95 (gcc) 14277 14278@geindex Ada 95 mode 14279 14280 14281@table @asis 14282 14283@item @code{-gnat95} (Ada 95 mode) 14284 14285This switch directs the compiler to implement the Ada 95 version of the 14286language. 14287Since Ada 95 is almost completely upwards 14288compatible with Ada 83, Ada 83 programs may generally be compiled using 14289this switch (see the description of the @code{-gnat83} switch for further 14290information about Ada 83 mode). 14291If an Ada 2005 program is compiled in Ada 95 mode, 14292uses of the new Ada 2005 features will cause error 14293messages or warnings. 14294 14295This switch also can be used to cancel the effect of a previous 14296@code{-gnat83}, @code{-gnat05/2005}, or @code{-gnat12/2012} 14297switch earlier in the command line. 14298@end table 14299 14300@geindex -gnat05 (gcc) 14301 14302@geindex -gnat2005 (gcc) 14303 14304@geindex Ada 2005 mode 14305 14306 14307@table @asis 14308 14309@item @code{-gnat05} or @code{-gnat2005} (Ada 2005 mode) 14310 14311This switch directs the compiler to implement the Ada 2005 version of the 14312language, as documented in the official Ada standards document. 14313Since Ada 2005 is almost completely upwards 14314compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs 14315may generally be compiled using this switch (see the description of the 14316@code{-gnat83} and @code{-gnat95} switches for further 14317information). 14318@end table 14319 14320@geindex -gnat12 (gcc) 14321 14322@geindex -gnat2012 (gcc) 14323 14324@geindex Ada 2012 mode 14325 14326 14327@table @asis 14328 14329@item @code{-gnat12} or @code{-gnat2012} (Ada 2012 mode) 14330 14331This switch directs the compiler to implement the Ada 2012 version of the 14332language (also the default). 14333Since Ada 2012 is almost completely upwards 14334compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), 14335Ada 83 and Ada 95 programs 14336may generally be compiled using this switch (see the description of the 14337@code{-gnat83}, @code{-gnat95}, and @code{-gnat05/2005} switches 14338for further information). 14339@end table 14340 14341@geindex -gnatX (gcc) 14342 14343@geindex Ada language extensions 14344 14345@geindex GNAT extensions 14346 14347 14348@table @asis 14349 14350@item @code{-gnatX} (Enable GNAT Extensions) 14351 14352This switch directs the compiler to implement the latest version of the 14353language (currently Ada 2012) and also to enable certain GNAT implementation 14354extensions that are not part of any Ada standard. For a full list of these 14355extensions, see the GNAT reference manual. 14356@end table 14357 14358@node Character Set Control,File Naming Control,Compiling Different Versions of Ada,Compiler Switches 14359@anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{fb}@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{31} 14360@subsection Character Set Control 14361 14362 14363@geindex -gnati (gcc) 14364 14365 14366@table @asis 14367 14368@item @code{-gnati@emph{c}} 14369 14370Normally GNAT recognizes the Latin-1 character set in source program 14371identifiers, as described in the Ada Reference Manual. 14372This switch causes 14373GNAT to recognize alternate character sets in identifiers. @code{c} is a 14374single character indicating the character set, as follows: 14375 14376 14377@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 14378@item 14379 14380@emph{1} 14381 14382@tab 14383 14384ISO 8859-1 (Latin-1) identifiers 14385 14386@item 14387 14388@emph{2} 14389 14390@tab 14391 14392ISO 8859-2 (Latin-2) letters allowed in identifiers 14393 14394@item 14395 14396@emph{3} 14397 14398@tab 14399 14400ISO 8859-3 (Latin-3) letters allowed in identifiers 14401 14402@item 14403 14404@emph{4} 14405 14406@tab 14407 14408ISO 8859-4 (Latin-4) letters allowed in identifiers 14409 14410@item 14411 14412@emph{5} 14413 14414@tab 14415 14416ISO 8859-5 (Cyrillic) letters allowed in identifiers 14417 14418@item 14419 14420@emph{9} 14421 14422@tab 14423 14424ISO 8859-15 (Latin-9) letters allowed in identifiers 14425 14426@item 14427 14428@emph{p} 14429 14430@tab 14431 14432IBM PC letters (code page 437) allowed in identifiers 14433 14434@item 14435 14436@emph{8} 14437 14438@tab 14439 14440IBM PC letters (code page 850) allowed in identifiers 14441 14442@item 14443 14444@emph{f} 14445 14446@tab 14447 14448Full upper-half codes allowed in identifiers 14449 14450@item 14451 14452@emph{n} 14453 14454@tab 14455 14456No upper-half codes allowed in identifiers 14457 14458@item 14459 14460@emph{w} 14461 14462@tab 14463 14464Wide-character codes (that is, codes greater than 255) 14465allowed in identifiers 14466 14467@end multitable 14468 14469 14470See @ref{23,,Foreign Language Representation} for full details on the 14471implementation of these character sets. 14472@end table 14473 14474@geindex -gnatW (gcc) 14475 14476 14477@table @asis 14478 14479@item @code{-gnatW@emph{e}} 14480 14481Specify the method of encoding for wide characters. 14482@code{e} is one of the following: 14483 14484 14485@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 14486@item 14487 14488@emph{h} 14489 14490@tab 14491 14492Hex encoding (brackets coding also recognized) 14493 14494@item 14495 14496@emph{u} 14497 14498@tab 14499 14500Upper half encoding (brackets encoding also recognized) 14501 14502@item 14503 14504@emph{s} 14505 14506@tab 14507 14508Shift/JIS encoding (brackets encoding also recognized) 14509 14510@item 14511 14512@emph{e} 14513 14514@tab 14515 14516EUC encoding (brackets encoding also recognized) 14517 14518@item 14519 14520@emph{8} 14521 14522@tab 14523 14524UTF-8 encoding (brackets encoding also recognized) 14525 14526@item 14527 14528@emph{b} 14529 14530@tab 14531 14532Brackets encoding only (default value) 14533 14534@end multitable 14535 14536 14537For full details on these encoding 14538methods see @ref{37,,Wide_Character Encodings}. 14539Note that brackets coding is always accepted, even if one of the other 14540options is specified, so for example @code{-gnatW8} specifies that both 14541brackets and UTF-8 encodings will be recognized. The units that are 14542with'ed directly or indirectly will be scanned using the specified 14543representation scheme, and so if one of the non-brackets scheme is 14544used, it must be used consistently throughout the program. However, 14545since brackets encoding is always recognized, it may be conveniently 14546used in standard libraries, allowing these libraries to be used with 14547any of the available coding schemes. 14548 14549Note that brackets encoding only applies to program text. Within comments, 14550brackets are considered to be normal graphic characters, and bracket sequences 14551are never recognized as wide characters. 14552 14553If no @code{-gnatW?} parameter is present, then the default 14554representation is normally Brackets encoding only. However, if the 14555first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard 14556byte order mark or BOM for UTF-8), then these three characters are 14557skipped and the default representation for the file is set to UTF-8. 14558 14559Note that the wide character representation that is specified (explicitly 14560or by default) for the main program also acts as the default encoding used 14561for Wide_Text_IO files if not specifically overridden by a WCEM form 14562parameter. 14563@end table 14564 14565When no @code{-gnatW?} is specified, then characters (other than wide 14566characters represented using brackets notation) are treated as 8-bit 14567Latin-1 codes. The codes recognized are the Latin-1 graphic characters, 14568and ASCII format effectors (CR, LF, HT, VT). Other lower half control 14569characters in the range 16#00#..16#1F# are not accepted in program text 14570or in comments. Upper half control characters (16#80#..16#9F#) are rejected 14571in program text, but allowed and ignored in comments. Note in particular 14572that the Next Line (NEL) character whose encoding is 16#85# is not recognized 14573as an end of line in this default mode. If your source program contains 14574instances of the NEL character used as a line terminator, 14575you must use UTF-8 encoding for the whole 14576source program. In default mode, all lines must be ended by a standard 14577end of line sequence (CR, CR/LF, or LF). 14578 14579Note that the convention of simply accepting all upper half characters in 14580comments means that programs that use standard ASCII for program text, but 14581UTF-8 encoding for comments are accepted in default mode, providing that the 14582comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator. 14583This is a common mode for many programs with foreign language comments. 14584 14585@node File Naming Control,Subprogram Inlining Control,Character Set Control,Compiler Switches 14586@anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{fc}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{fd} 14587@subsection File Naming Control 14588 14589 14590@geindex -gnatk (gcc) 14591 14592 14593@table @asis 14594 14595@item @code{-gnatk@emph{n}} 14596 14597Activates file name 'krunching'. @code{n}, a decimal integer in the range 145981-999, indicates the maximum allowable length of a file name (not 14599including the @code{.ads} or @code{.adb} extension). The default is not 14600to enable file name krunching. 14601 14602For the source file naming rules, @ref{3b,,File Naming Rules}. 14603@end table 14604 14605@node Subprogram Inlining Control,Auxiliary Output Control,File Naming Control,Compiler Switches 14606@anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{ff} 14607@subsection Subprogram Inlining Control 14608 14609 14610@geindex -gnatn (gcc) 14611 14612 14613@table @asis 14614 14615@item @code{-gnatn[12]} 14616 14617The @code{n} here is intended to suggest the first syllable of the word 'inline'. 14618GNAT recognizes and processes @code{Inline} pragmas. However, for inlining to 14619actually occur, optimization must be enabled and, by default, inlining of 14620subprograms across units is not performed. If you want to additionally 14621enable inlining of subprograms specified by pragma @code{Inline} across units, 14622you must also specify this switch. 14623 14624In the absence of this switch, GNAT does not attempt inlining across units 14625and does not access the bodies of subprograms for which @code{pragma Inline} is 14626specified if they are not in the current unit. 14627 14628You can optionally specify the inlining level: 1 for moderate inlining across 14629units, which is a good compromise between compilation times and performances 14630at run time, or 2 for full inlining across units, which may bring about 14631longer compilation times. If no inlining level is specified, the compiler will 14632pick it based on the optimization level: 1 for @code{-O1}, @code{-O2} or 14633@code{-Os} and 2 for @code{-O3}. 14634 14635If you specify this switch the compiler will access these bodies, 14636creating an extra source dependency for the resulting object file, and 14637where possible, the call will be inlined. 14638For further details on when inlining is possible 14639see @ref{100,,Inlining of Subprograms}. 14640@end table 14641 14642@geindex -gnatN (gcc) 14643 14644 14645@table @asis 14646 14647@item @code{-gnatN} 14648 14649This switch activates front-end inlining which also 14650generates additional dependencies. 14651 14652When using a gcc-based back end (in practice this means using any version 14653of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of 14654@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred. 14655Historically front end inlining was more extensive than the gcc back end 14656inlining, but that is no longer the case. 14657@end table 14658 14659@node Auxiliary Output Control,Debugging Control,Subprogram Inlining Control,Compiler Switches 14660@anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{101}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{102} 14661@subsection Auxiliary Output Control 14662 14663 14664@geindex -gnatu (gcc) 14665 14666 14667@table @asis 14668 14669@item @code{-gnatu} 14670 14671Print a list of units required by this compilation on @code{stdout}. 14672The listing includes all units on which the unit being compiled depends 14673either directly or indirectly. 14674@end table 14675 14676@geindex -pass-exit-codes (gcc) 14677 14678 14679@table @asis 14680 14681@item @code{-pass-exit-codes} 14682 14683If this switch is not used, the exit code returned by @code{gcc} when 14684compiling multiple files indicates whether all source files have 14685been successfully used to generate object files or not. 14686 14687When @code{-pass-exit-codes} is used, @code{gcc} exits with an extended 14688exit status and allows an integrated development environment to better 14689react to a compilation failure. Those exit status are: 14690 14691 14692@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 14693@item 14694 14695@emph{5} 14696 14697@tab 14698 14699There was an error in at least one source file. 14700 14701@item 14702 14703@emph{3} 14704 14705@tab 14706 14707At least one source file did not generate an object file. 14708 14709@item 14710 14711@emph{2} 14712 14713@tab 14714 14715The compiler died unexpectedly (internal error for example). 14716 14717@item 14718 14719@emph{0} 14720 14721@tab 14722 14723An object file has been generated for every source file. 14724 14725@end multitable 14726 14727@end table 14728 14729@node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches 14730@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{103}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{104} 14731@subsection Debugging Control 14732 14733 14734@quotation 14735 14736@geindex Debugging options 14737@end quotation 14738 14739@geindex -gnatd (gcc) 14740 14741 14742@table @asis 14743 14744@item @code{-gnatd@emph{x}} 14745 14746Activate internal debugging switches. @code{x} is a letter or digit, or 14747string of letters or digits, which specifies the type of debugging 14748outputs desired. Normally these are used only for internal development 14749or system debugging purposes. You can find full documentation for these 14750switches in the body of the @code{Debug} unit in the compiler source 14751file @code{debug.adb}. 14752@end table 14753 14754@geindex -gnatG (gcc) 14755 14756 14757@table @asis 14758 14759@item @code{-gnatG[=@emph{nn}]} 14760 14761This switch causes the compiler to generate auxiliary output containing 14762a pseudo-source listing of the generated expanded code. Like most Ada 14763compilers, GNAT works by first transforming the high level Ada code into 14764lower level constructs. For example, tasking operations are transformed 14765into calls to the tasking run-time routines. A unique capability of GNAT 14766is to list this expanded code in a form very close to normal Ada source. 14767This is very useful in understanding the implications of various Ada 14768usage on the efficiency of the generated code. There are many cases in 14769Ada (e.g., the use of controlled types), where simple Ada statements can 14770generate a lot of run-time code. By using @code{-gnatG} you can identify 14771these cases, and consider whether it may be desirable to modify the coding 14772approach to improve efficiency. 14773 14774The optional parameter @code{nn} if present after -gnatG specifies an 14775alternative maximum line length that overrides the normal default of 72. 14776This value is in the range 40-999999, values less than 40 being silently 14777reset to 40. The equal sign is optional. 14778 14779The format of the output is very similar to standard Ada source, and is 14780easily understood by an Ada programmer. The following special syntactic 14781additions correspond to low level features used in the generated code that 14782do not have any exact analogies in pure Ada source form. The following 14783is a partial list of these special constructions. See the spec 14784of package @code{Sprint} in file @code{sprint.ads} for a full list. 14785 14786@geindex -gnatL (gcc) 14787 14788If the switch @code{-gnatL} is used in conjunction with 14789@code{-gnatG}, then the original source lines are interspersed 14790in the expanded source (as comment lines with the original line number). 14791 14792 14793@table @asis 14794 14795@item @code{new @emph{xxx} [storage_pool = @emph{yyy}]} 14796 14797Shows the storage pool being used for an allocator. 14798 14799@item @code{at end @emph{procedure-name};} 14800 14801Shows the finalization (cleanup) procedure for a scope. 14802 14803@item @code{(if @emph{expr} then @emph{expr} else @emph{expr})} 14804 14805Conditional expression equivalent to the @code{x?y:z} construction in C. 14806 14807@item @code{@emph{target}^(@emph{source})} 14808 14809A conversion with floating-point truncation instead of rounding. 14810 14811@item @code{@emph{target}?(@emph{source})} 14812 14813A conversion that bypasses normal Ada semantic checking. In particular 14814enumeration types and fixed-point types are treated simply as integers. 14815 14816@item @code{@emph{target}?^(@emph{source})} 14817 14818Combines the above two cases. 14819@end table 14820 14821@code{@emph{x} #/ @emph{y}} 14822 14823@code{@emph{x} #mod @emph{y}} 14824 14825@code{@emph{x} # @emph{y}} 14826 14827 14828@table @asis 14829 14830@item @code{@emph{x} #rem @emph{y}} 14831 14832A division or multiplication of fixed-point values which are treated as 14833integers without any kind of scaling. 14834 14835@item @code{free @emph{expr} [storage_pool = @emph{xxx}]} 14836 14837Shows the storage pool associated with a @code{free} statement. 14838 14839@item @code{[subtype or type declaration]} 14840 14841Used to list an equivalent declaration for an internally generated 14842type that is referenced elsewhere in the listing. 14843 14844@item @code{freeze @emph{type-name} [@emph{actions}]} 14845 14846Shows the point at which @code{type-name} is frozen, with possible 14847associated actions to be performed at the freeze point. 14848 14849@item @code{reference @emph{itype}} 14850 14851Reference (and hence definition) to internal type @code{itype}. 14852 14853@item @code{@emph{function-name}! (@emph{arg}, @emph{arg}, @emph{arg})} 14854 14855Intrinsic function call. 14856 14857@item @code{@emph{label-name} : label} 14858 14859Declaration of label @code{labelname}. 14860 14861@item @code{#$ @emph{subprogram-name}} 14862 14863An implicit call to a run-time support routine 14864(to meet the requirement of H.3.1(9) in a 14865convenient manner). 14866 14867@item @code{@emph{expr} && @emph{expr} && @emph{expr} ... && @emph{expr}} 14868 14869A multiple concatenation (same effect as @code{expr} & @code{expr} & 14870@code{expr}, but handled more efficiently). 14871 14872@item @code{[constraint_error]} 14873 14874Raise the @code{Constraint_Error} exception. 14875 14876@item @code{@emph{expression}'reference} 14877 14878A pointer to the result of evaluating @{expression@}. 14879 14880@item @code{@emph{target-type}!(@emph{source-expression})} 14881 14882An unchecked conversion of @code{source-expression} to @code{target-type}. 14883 14884@item @code{[@emph{numerator}/@emph{denominator}]} 14885 14886Used to represent internal real literals (that) have no exact 14887representation in base 2-16 (for example, the result of compile time 14888evaluation of the expression 1.0/27.0). 14889@end table 14890@end table 14891 14892@geindex -gnatD (gcc) 14893 14894 14895@table @asis 14896 14897@item @code{-gnatD[=nn]} 14898 14899When used in conjunction with @code{-gnatG}, this switch causes 14900the expanded source, as described above for 14901@code{-gnatG} to be written to files with names 14902@code{xxx.dg}, where @code{xxx} is the normal file name, 14903instead of to the standard output file. For 14904example, if the source file name is @code{hello.adb}, then a file 14905@code{hello.adb.dg} will be written. The debugging 14906information generated by the @code{gcc} @code{-g} switch 14907will refer to the generated @code{xxx.dg} file. This allows 14908you to do source level debugging using the generated code which is 14909sometimes useful for complex code, for example to find out exactly 14910which part of a complex construction raised an exception. This switch 14911also suppresses generation of cross-reference information (see 14912@code{-gnatx}) since otherwise the cross-reference information 14913would refer to the @code{.dg} file, which would cause 14914confusion since this is not the original source file. 14915 14916Note that @code{-gnatD} actually implies @code{-gnatG} 14917automatically, so it is not necessary to give both options. 14918In other words @code{-gnatD} is equivalent to @code{-gnatDG}). 14919 14920@geindex -gnatL (gcc) 14921 14922If the switch @code{-gnatL} is used in conjunction with 14923@code{-gnatDG}, then the original source lines are interspersed 14924in the expanded source (as comment lines with the original line number). 14925 14926The optional parameter @code{nn} if present after -gnatD specifies an 14927alternative maximum line length that overrides the normal default of 72. 14928This value is in the range 40-999999, values less than 40 being silently 14929reset to 40. The equal sign is optional. 14930@end table 14931 14932@geindex -gnatr (gcc) 14933 14934@geindex pragma Restrictions 14935 14936 14937@table @asis 14938 14939@item @code{-gnatr} 14940 14941This switch causes pragma Restrictions to be treated as Restriction_Warnings 14942so that violation of restrictions causes warnings rather than illegalities. 14943This is useful during the development process when new restrictions are added 14944or investigated. The switch also causes pragma Profile to be treated as 14945Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set 14946restriction warnings rather than restrictions. 14947@end table 14948 14949@geindex -gnatR (gcc) 14950 14951 14952@table @asis 14953 14954@item @code{-gnatR[0|1|2|3|4][e][j][m][s]} 14955 14956This switch controls output from the compiler of a listing showing 14957representation information for declared types, objects and subprograms. 14958For @code{-gnatR0}, no information is output (equivalent to omitting 14959the @code{-gnatR} switch). For @code{-gnatR1} (which is the default, 14960so @code{-gnatR} with no parameter has the same effect), size and 14961alignment information is listed for declared array and record types. 14962 14963For @code{-gnatR2}, size and alignment information is listed for all 14964declared types and objects. The @code{Linker_Section} is also listed for any 14965entity for which the @code{Linker_Section} is set explicitly or implicitly (the 14966latter case occurs for objects of a type for which a @code{Linker_Section} 14967is set). 14968 14969For @code{-gnatR3}, symbolic expressions for values that are computed 14970at run time for records are included. These symbolic expressions have 14971a mostly obvious format with #n being used to represent the value of the 14972n'th discriminant. See source files @code{repinfo.ads/adb} in the 14973GNAT sources for full details on the format of @code{-gnatR3} output. 14974 14975For @code{-gnatR4}, information for relevant compiler-generated types 14976is also listed, i.e. when they are structurally part of other declared 14977types and objects. 14978 14979If the switch is followed by an @code{e} (e.g. @code{-gnatR2e}), then 14980extended representation information for record sub-components of records 14981is included. 14982 14983If the switch is followed by an @code{m} (e.g. @code{-gnatRm}), then 14984subprogram conventions and parameter passing mechanisms for all the 14985subprograms are included. 14986 14987If the switch is followed by a @code{j} (e.g., @code{-gnatRj}), then 14988the output is in the JSON data interchange format specified by the 14989ECMA-404 standard. The semantic description of this JSON output is 14990available in the specification of the Repinfo unit present in the 14991compiler sources. 14992 14993If the switch is followed by an @code{s} (e.g., @code{-gnatR3s}), then 14994the output is to a file with the name @code{file.rep} where @code{file} is 14995the name of the corresponding source file, except if @code{j} is also 14996specified, in which case the file name is @code{file.json}. 14997 14998Note that it is possible for record components to have zero size. In 14999this case, the component clause uses an obvious extension of permitted 15000Ada syntax, for example @code{at 0 range 0 .. -1}. 15001@end table 15002 15003@geindex -gnatS (gcc) 15004 15005 15006@table @asis 15007 15008@item @code{-gnatS} 15009 15010The use of the switch @code{-gnatS} for an 15011Ada compilation will cause the compiler to output a 15012representation of package Standard in a form very 15013close to standard Ada. It is not quite possible to 15014do this entirely in standard Ada (since new 15015numeric base types cannot be created in standard 15016Ada), but the output is easily 15017readable to any Ada programmer, and is useful to 15018determine the characteristics of target dependent 15019types in package Standard. 15020@end table 15021 15022@geindex -gnatx (gcc) 15023 15024 15025@table @asis 15026 15027@item @code{-gnatx} 15028 15029Normally the compiler generates full cross-referencing information in 15030the @code{ALI} file. This information is used by a number of tools, 15031including @code{gnatfind} and @code{gnatxref}. The @code{-gnatx} switch 15032suppresses this information. This saves some space and may slightly 15033speed up compilation, but means that these tools cannot be used. 15034@end table 15035 15036@geindex -fgnat-encodings (gcc) 15037 15038 15039@table @asis 15040 15041@item @code{-fgnat-encodings=[all|gdb|minimal]} 15042 15043This switch controls the balance between GNAT encodings and standard DWARF 15044emitted in the debug information. 15045 15046Historically, old debug formats like stabs were not powerful enough to 15047express some Ada types (for instance, variant records or fixed-point types). 15048To work around this, GNAT introduced proprietary encodings that embed the 15049missing information ("GNAT encodings"). 15050 15051Recent versions of the DWARF debug information format are now able to 15052correctly describe most of these Ada constructs ("standard DWARF"). As 15053third-party tools started to use this format, GNAT has been enhanced to 15054generate it. However, most tools (including GDB) are still relying on GNAT 15055encodings. 15056 15057To support all tools, GNAT needs to be versatile about the balance between 15058generation of GNAT encodings and standard DWARF. This is what 15059@code{-fgnat-encodings} is about. 15060 15061 15062@itemize * 15063 15064@item 15065@code{=all}: Emit all GNAT encodings, and then emit as much standard DWARF as 15066possible so it does not conflict with GNAT encodings. 15067 15068@item 15069@code{=gdb}: Emit as much standard DWARF as possible as long as the current 15070GDB handles it. Emit GNAT encodings for the rest. 15071 15072@item 15073@code{=minimal}: Emit as much standard DWARF as possible and emit GNAT 15074encodings for the rest. 15075@end itemize 15076@end table 15077 15078@node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches 15079@anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{106} 15080@subsection Exception Handling Control 15081 15082 15083GNAT uses two methods for handling exceptions at run time. The 15084@code{setjmp/longjmp} method saves the context when entering 15085a frame with an exception handler. Then when an exception is 15086raised, the context can be restored immediately, without the 15087need for tracing stack frames. This method provides very fast 15088exception propagation, but introduces significant overhead for 15089the use of exception handlers, even if no exception is raised. 15090 15091The other approach is called 'zero cost' exception handling. 15092With this method, the compiler builds static tables to describe 15093the exception ranges. No dynamic code is required when entering 15094a frame containing an exception handler. When an exception is 15095raised, the tables are used to control a back trace of the 15096subprogram invocation stack to locate the required exception 15097handler. This method has considerably poorer performance for 15098the propagation of exceptions, but there is no overhead for 15099exception handlers if no exception is raised. Note that in this 15100mode and in the context of mixed Ada and C/C++ programming, 15101to propagate an exception through a C/C++ code, the C/C++ code 15102must be compiled with the @code{-funwind-tables} GCC's 15103option. 15104 15105The following switches may be used to control which of the 15106two exception handling methods is used. 15107 15108@geindex --RTS=sjlj (gnatmake) 15109 15110 15111@table @asis 15112 15113@item @code{--RTS=sjlj} 15114 15115This switch causes the setjmp/longjmp run-time (when available) to be used 15116for exception handling. If the default 15117mechanism for the target is zero cost exceptions, then 15118this switch can be used to modify this default, and must be 15119used for all units in the partition. 15120This option is rarely used. One case in which it may be 15121advantageous is if you have an application where exception 15122raising is common and the overall performance of the 15123application is improved by favoring exception propagation. 15124@end table 15125 15126@geindex --RTS=zcx (gnatmake) 15127 15128@geindex Zero Cost Exceptions 15129 15130 15131@table @asis 15132 15133@item @code{--RTS=zcx} 15134 15135This switch causes the zero cost approach to be used 15136for exception handling. If this is the default mechanism for the 15137target (see below), then this switch is unneeded. If the default 15138mechanism for the target is setjmp/longjmp exceptions, then 15139this switch can be used to modify this default, and must be 15140used for all units in the partition. 15141This option can only be used if the zero cost approach 15142is available for the target in use, otherwise it will generate an error. 15143@end table 15144 15145The same option @code{--RTS} must be used both for @code{gcc} 15146and @code{gnatbind}. Passing this option to @code{gnatmake} 15147(@ref{cd,,Switches for gnatmake}) will ensure the required consistency 15148through the compilation and binding steps. 15149 15150@node Units to Sources Mapping Files,Code Generation Control,Exception Handling Control,Compiler Switches 15151@anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{e8} 15152@subsection Units to Sources Mapping Files 15153 15154 15155@geindex -gnatem (gcc) 15156 15157 15158@table @asis 15159 15160@item @code{-gnatem=@emph{path}} 15161 15162A mapping file is a way to communicate to the compiler two mappings: 15163from unit names to file names (without any directory information) and from 15164file names to path names (with full directory information). These mappings 15165are used by the compiler to short-circuit the path search. 15166 15167The use of mapping files is not required for correct operation of the 15168compiler, but mapping files can improve efficiency, particularly when 15169sources are read over a slow network connection. In normal operation, 15170you need not be concerned with the format or use of mapping files, 15171and the @code{-gnatem} switch is not a switch that you would use 15172explicitly. It is intended primarily for use by automatic tools such as 15173@code{gnatmake} running under the project file facility. The 15174description here of the format of mapping files is provided 15175for completeness and for possible use by other tools. 15176 15177A mapping file is a sequence of sets of three lines. In each set, the 15178first line is the unit name, in lower case, with @code{%s} appended 15179for specs and @code{%b} appended for bodies; the second line is the 15180file name; and the third line is the path name. 15181 15182Example: 15183 15184@example 15185main%b 15186main.2.ada 15187/gnat/project1/sources/main.2.ada 15188@end example 15189 15190When the switch @code{-gnatem} is specified, the compiler will 15191create in memory the two mappings from the specified file. If there is 15192any problem (nonexistent file, truncated file or duplicate entries), 15193no mapping will be created. 15194 15195Several @code{-gnatem} switches may be specified; however, only the 15196last one on the command line will be taken into account. 15197 15198When using a project file, @code{gnatmake} creates a temporary 15199mapping file and communicates it to the compiler using this switch. 15200@end table 15201 15202@node Code Generation Control,,Units to Sources Mapping Files,Compiler Switches 15203@anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{108}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{109} 15204@subsection Code Generation Control 15205 15206 15207The GCC technology provides a wide range of target dependent 15208@code{-m} switches for controlling 15209details of code generation with respect to different versions of 15210architectures. This includes variations in instruction sets (e.g., 15211different members of the power pc family), and different requirements 15212for optimal arrangement of instructions (e.g., different members of 15213the x86 family). The list of available @code{-m} switches may be 15214found in the GCC documentation. 15215 15216Use of these @code{-m} switches may in some cases result in improved 15217code performance. 15218 15219The GNAT technology is tested and qualified without any 15220@code{-m} switches, 15221so generally the most reliable approach is to avoid the use of these 15222switches. However, we generally expect most of these switches to work 15223successfully with GNAT, and many customers have reported successful 15224use of these options. 15225 15226Our general advice is to avoid the use of @code{-m} switches unless 15227special needs lead to requirements in this area. In particular, 15228there is no point in using @code{-m} switches to improve performance 15229unless you actually see a performance improvement. 15230 15231@node Linker Switches,Binding with gnatbind,Compiler Switches,Building Executable Programs with GNAT 15232@anchor{gnat_ugn/building_executable_programs_with_gnat linker-switches}@anchor{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{10b} 15233@section Linker Switches 15234 15235 15236Linker switches can be specified after @code{-largs} builder switch. 15237 15238@geindex -fuse-ld=name 15239 15240 15241@table @asis 15242 15243@item @code{-fuse-ld=@emph{name}} 15244 15245Linker to be used. The default is @code{bfd} for @code{ld.bfd}, 15246the alternative being @code{gold} for @code{ld.gold}. The later is 15247a more recent and faster linker, but only available on GNU/Linux 15248platforms. 15249@end table 15250 15251@node Binding with gnatbind,Linking with gnatlink,Linker Switches,Building Executable Programs with GNAT 15252@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{c8}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{10c} 15253@section Binding with @code{gnatbind} 15254 15255 15256@geindex gnatbind 15257 15258This chapter describes the GNAT binder, @code{gnatbind}, which is used 15259to bind compiled GNAT objects. 15260 15261The @code{gnatbind} program performs four separate functions: 15262 15263 15264@itemize * 15265 15266@item 15267Checks that a program is consistent, in accordance with the rules in 15268Chapter 10 of the Ada Reference Manual. In particular, error 15269messages are generated if a program uses inconsistent versions of a 15270given unit. 15271 15272@item 15273Checks that an acceptable order of elaboration exists for the program 15274and issues an error message if it cannot find an order of elaboration 15275that satisfies the rules in Chapter 10 of the Ada Language Manual. 15276 15277@item 15278Generates a main program incorporating the given elaboration order. 15279This program is a small Ada package (body and spec) that 15280must be subsequently compiled 15281using the GNAT compiler. The necessary compilation step is usually 15282performed automatically by @code{gnatlink}. The two most important 15283functions of this program 15284are to call the elaboration routines of units in an appropriate order 15285and to call the main program. 15286 15287@item 15288Determines the set of object files required by the given main program. 15289This information is output in the forms of comments in the generated program, 15290to be read by the @code{gnatlink} utility used to link the Ada application. 15291@end itemize 15292 15293@menu 15294* Running gnatbind:: 15295* Switches for gnatbind:: 15296* Command-Line Access:: 15297* Search Paths for gnatbind:: 15298* Examples of gnatbind Usage:: 15299 15300@end menu 15301 15302@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind 15303@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{10e} 15304@subsection Running @code{gnatbind} 15305 15306 15307The form of the @code{gnatbind} command is 15308 15309@example 15310$ gnatbind [ switches ] mainprog[.ali] [ switches ] 15311@end example 15312 15313where @code{mainprog.adb} is the Ada file containing the main program 15314unit body. @code{gnatbind} constructs an Ada 15315package in two files whose names are 15316@code{b~mainprog.ads}, and @code{b~mainprog.adb}. 15317For example, if given the 15318parameter @code{hello.ali}, for a main program contained in file 15319@code{hello.adb}, the binder output files would be @code{b~hello.ads} 15320and @code{b~hello.adb}. 15321 15322When doing consistency checking, the binder takes into consideration 15323any source files it can locate. For example, if the binder determines 15324that the given main program requires the package @code{Pack}, whose 15325@code{.ALI} 15326file is @code{pack.ali} and whose corresponding source spec file is 15327@code{pack.ads}, it attempts to locate the source file @code{pack.ads} 15328(using the same search path conventions as previously described for the 15329@code{gcc} command). If it can locate this source file, it checks that 15330the time stamps 15331or source checksums of the source and its references to in @code{ALI} files 15332match. In other words, any @code{ALI} files that mentions this spec must have 15333resulted from compiling this version of the source file (or in the case 15334where the source checksums match, a version close enough that the 15335difference does not matter). 15336 15337@geindex Source files 15338@geindex use by binder 15339 15340The effect of this consistency checking, which includes source files, is 15341that the binder ensures that the program is consistent with the latest 15342version of the source files that can be located at bind time. Editing a 15343source file without compiling files that depend on the source file cause 15344error messages to be generated by the binder. 15345 15346For example, suppose you have a main program @code{hello.adb} and a 15347package @code{P}, from file @code{p.ads} and you perform the following 15348steps: 15349 15350 15351@itemize * 15352 15353@item 15354Enter @code{gcc -c hello.adb} to compile the main program. 15355 15356@item 15357Enter @code{gcc -c p.ads} to compile package @code{P}. 15358 15359@item 15360Edit file @code{p.ads}. 15361 15362@item 15363Enter @code{gnatbind hello}. 15364@end itemize 15365 15366At this point, the file @code{p.ali} contains an out-of-date time stamp 15367because the file @code{p.ads} has been edited. The attempt at binding 15368fails, and the binder generates the following error messages: 15369 15370@example 15371error: "hello.adb" must be recompiled ("p.ads" has been modified) 15372error: "p.ads" has been modified and must be recompiled 15373@end example 15374 15375Now both files must be recompiled as indicated, and then the bind can 15376succeed, generating a main program. You need not normally be concerned 15377with the contents of this file, but for reference purposes a sample 15378binder output file is given in @ref{e,,Example of Binder Output File}. 15379 15380In most normal usage, the default mode of @code{gnatbind} which is to 15381generate the main package in Ada, as described in the previous section. 15382In particular, this means that any Ada programmer can read and understand 15383the generated main program. It can also be debugged just like any other 15384Ada code provided the @code{-g} switch is used for 15385@code{gnatbind} and @code{gnatlink}. 15386 15387@node Switches for gnatbind,Command-Line Access,Running gnatbind,Binding with gnatbind 15388@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{110} 15389@subsection Switches for @code{gnatbind} 15390 15391 15392The following switches are available with @code{gnatbind}; details will 15393be presented in subsequent sections. 15394 15395@geindex --version (gnatbind) 15396 15397 15398@table @asis 15399 15400@item @code{--version} 15401 15402Display Copyright and version, then exit disregarding all other options. 15403@end table 15404 15405@geindex --help (gnatbind) 15406 15407 15408@table @asis 15409 15410@item @code{--help} 15411 15412If @code{--version} was not used, display usage, then exit disregarding 15413all other options. 15414@end table 15415 15416@geindex -a (gnatbind) 15417 15418 15419@table @asis 15420 15421@item @code{-a} 15422 15423Indicates that, if supported by the platform, the adainit procedure should 15424be treated as an initialisation routine by the linker (a constructor). This 15425is intended to be used by the Project Manager to automatically initialize 15426shared Stand-Alone Libraries. 15427@end table 15428 15429@geindex -aO (gnatbind) 15430 15431 15432@table @asis 15433 15434@item @code{-aO} 15435 15436Specify directory to be searched for ALI files. 15437@end table 15438 15439@geindex -aI (gnatbind) 15440 15441 15442@table @asis 15443 15444@item @code{-aI} 15445 15446Specify directory to be searched for source file. 15447@end table 15448 15449@geindex -A (gnatbind) 15450 15451 15452@table @asis 15453 15454@item @code{-A[=@emph{filename}]} 15455 15456Output ALI list (to standard output or to the named file). 15457@end table 15458 15459@geindex -b (gnatbind) 15460 15461 15462@table @asis 15463 15464@item @code{-b} 15465 15466Generate brief messages to @code{stderr} even if verbose mode set. 15467@end table 15468 15469@geindex -c (gnatbind) 15470 15471 15472@table @asis 15473 15474@item @code{-c} 15475 15476Check only, no generation of binder output file. 15477@end table 15478 15479@geindex -dnn[k|m] (gnatbind) 15480 15481 15482@table @asis 15483 15484@item @code{-d@emph{nn}[k|m]} 15485 15486This switch can be used to change the default task stack size value 15487to a specified size @code{nn}, which is expressed in bytes by default, or 15488in kilobytes when suffixed with @code{k} or in megabytes when suffixed 15489with @code{m}. 15490In the absence of a @code{[k|m]} suffix, this switch is equivalent, 15491in effect, to completing all task specs with 15492 15493@example 15494pragma Storage_Size (nn); 15495@end example 15496 15497When they do not already have such a pragma. 15498@end table 15499 15500@geindex -D (gnatbind) 15501 15502 15503@table @asis 15504 15505@item @code{-D@emph{nn}[k|m]} 15506 15507Set the default secondary stack size to @code{nn}. The suffix indicates whether 15508the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes 15509(@code{m} suffix). 15510 15511The secondary stack holds objects of unconstrained types that are returned by 15512functions, for example unconstrained Strings. The size of the secondary stack 15513can be dynamic or fixed depending on the target. 15514 15515For most targets, the secondary stack grows on demand and is implemented as 15516a chain of blocks in the heap. In this case, the default secondary stack size 15517determines the initial size of the secondary stack for each task and the 15518smallest amount the secondary stack can grow by. 15519 15520For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is 15521fixed. This switch can be used to change the default size of these stacks. 15522The default secondary stack size can be overridden on a per-task basis if 15523individual tasks have different secondary stack requirements. This is 15524achieved through the Secondary_Stack_Size aspect that takes the size of the 15525secondary stack in bytes. 15526@end table 15527 15528@geindex -e (gnatbind) 15529 15530 15531@table @asis 15532 15533@item @code{-e} 15534 15535Output complete list of elaboration-order dependencies. 15536@end table 15537 15538@geindex -Ea (gnatbind) 15539 15540 15541@table @asis 15542 15543@item @code{-Ea} 15544 15545Store tracebacks in exception occurrences when the target supports it. 15546The "a" is for "address"; tracebacks will contain hexadecimal addresses, 15547unless symbolic tracebacks are enabled. 15548 15549See also the packages @code{GNAT.Traceback} and 15550@code{GNAT.Traceback.Symbolic} for more information. 15551Note that on x86 ports, you must not use @code{-fomit-frame-pointer} 15552@code{gcc} option. 15553@end table 15554 15555@geindex -Es (gnatbind) 15556 15557 15558@table @asis 15559 15560@item @code{-Es} 15561 15562Store tracebacks in exception occurrences when the target supports it. 15563The "s" is for "symbolic"; symbolic tracebacks are enabled. 15564@end table 15565 15566@geindex -E (gnatbind) 15567 15568 15569@table @asis 15570 15571@item @code{-E} 15572 15573Currently the same as @code{-Ea}. 15574@end table 15575 15576@geindex -f (gnatbind) 15577 15578 15579@table @asis 15580 15581@item @code{-f@emph{elab-order}} 15582 15583Force elaboration order. For further details see @ref{111,,Elaboration Control} 15584and @ref{f,,Elaboration Order Handling in GNAT}. 15585@end table 15586 15587@geindex -F (gnatbind) 15588 15589 15590@table @asis 15591 15592@item @code{-F} 15593 15594Force the checks of elaboration flags. @code{gnatbind} does not normally 15595generate checks of elaboration flags for the main executable, except when 15596a Stand-Alone Library is used. However, there are cases when this cannot be 15597detected by gnatbind. An example is importing an interface of a Stand-Alone 15598Library through a pragma Import and only specifying through a linker switch 15599this Stand-Alone Library. This switch is used to guarantee that elaboration 15600flag checks are generated. 15601@end table 15602 15603@geindex -h (gnatbind) 15604 15605 15606@table @asis 15607 15608@item @code{-h} 15609 15610Output usage (help) information. 15611@end table 15612 15613@geindex -H (gnatbind) 15614 15615 15616@table @asis 15617 15618@item @code{-H} 15619 15620Legacy elaboration order model enabled. For further details see 15621@ref{f,,Elaboration Order Handling in GNAT}. 15622@end table 15623 15624@geindex -H32 (gnatbind) 15625 15626 15627@table @asis 15628 15629@item @code{-H32} 15630 15631Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types). 15632For further details see @ref{112,,Dynamic Allocation Control}. 15633@end table 15634 15635@geindex -H64 (gnatbind) 15636 15637@geindex __gnat_malloc 15638 15639 15640@table @asis 15641 15642@item @code{-H64} 15643 15644Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types). 15645For further details see @ref{112,,Dynamic Allocation Control}. 15646 15647@geindex -I (gnatbind) 15648 15649@item @code{-I} 15650 15651Specify directory to be searched for source and ALI files. 15652 15653@geindex -I- (gnatbind) 15654 15655@item @code{-I-} 15656 15657Do not look for sources in the current directory where @code{gnatbind} was 15658invoked, and do not look for ALI files in the directory containing the 15659ALI file named in the @code{gnatbind} command line. 15660 15661@geindex -l (gnatbind) 15662 15663@item @code{-l} 15664 15665Output chosen elaboration order. 15666 15667@geindex -L (gnatbind) 15668 15669@item @code{-L@emph{xxx}} 15670 15671Bind the units for library building. In this case the @code{adainit} and 15672@code{adafinal} procedures (@ref{a0,,Binding with Non-Ada Main Programs}) 15673are renamed to @code{@emph{xxx}init} and 15674@code{@emph{xxx}final}. 15675Implies -n. 15676(@ref{2a,,GNAT and Libraries}, for more details.) 15677 15678@geindex -M (gnatbind) 15679 15680@item @code{-M@emph{xyz}} 15681 15682Rename generated main program from main to xyz. This option is 15683supported on cross environments only. 15684 15685@geindex -m (gnatbind) 15686 15687@item @code{-m@emph{n}} 15688 15689Limit number of detected errors or warnings to @code{n}, where @code{n} is 15690in the range 1..999999. The default value if no switch is 15691given is 9999. If the number of warnings reaches this limit, then a 15692message is output and further warnings are suppressed, the bind 15693continues in this case. If the number of errors reaches this 15694limit, then a message is output and the bind is abandoned. 15695A value of zero means that no limit is enforced. The equal 15696sign is optional. 15697 15698@geindex -minimal (gnatbind) 15699 15700@item @code{-minimal} 15701 15702Generate a binder file suitable for space-constrained applications. When 15703active, binder-generated objects not required for program operation are no 15704longer generated. @strong{Warning:} this option comes with the following 15705limitations: 15706 15707 15708@itemize * 15709 15710@item 15711Starting the program's execution in the debugger will cause it to 15712stop at the start of the @code{main} function instead of the main subprogram. 15713This can be worked around by manually inserting a breakpoint on that 15714subprogram and resuming the program's execution until reaching that breakpoint. 15715 15716@item 15717Programs using GNAT.Compiler_Version will not link. 15718@end itemize 15719 15720@geindex -n (gnatbind) 15721 15722@item @code{-n} 15723 15724No main program. 15725 15726@geindex -nostdinc (gnatbind) 15727 15728@item @code{-nostdinc} 15729 15730Do not look for sources in the system default directory. 15731 15732@geindex -nostdlib (gnatbind) 15733 15734@item @code{-nostdlib} 15735 15736Do not look for library files in the system default directory. 15737 15738@geindex --RTS (gnatbind) 15739 15740@item @code{--RTS=@emph{rts-path}} 15741 15742Specifies the default location of the run-time library. Same meaning as the 15743equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}). 15744 15745@geindex -o (gnatbind) 15746 15747@item @code{-o @emph{file}} 15748 15749Name the output file @code{file} (default is @code{b~`xxx}.adb`). 15750Note that if this option is used, then linking must be done manually, 15751gnatlink cannot be used. 15752 15753@geindex -O (gnatbind) 15754 15755@item @code{-O[=@emph{filename}]} 15756 15757Output object list (to standard output or to the named file). 15758 15759@geindex -p (gnatbind) 15760 15761@item @code{-p} 15762 15763Pessimistic (worst-case) elaboration order. 15764 15765@geindex -P (gnatbind) 15766 15767@item @code{-P} 15768 15769Generate binder file suitable for CodePeer. 15770 15771@geindex -R (gnatbind) 15772 15773@item @code{-R} 15774 15775Output closure source list, which includes all non-run-time units that are 15776included in the bind. 15777 15778@geindex -Ra (gnatbind) 15779 15780@item @code{-Ra} 15781 15782Like @code{-R} but the list includes run-time units. 15783 15784@geindex -s (gnatbind) 15785 15786@item @code{-s} 15787 15788Require all source files to be present. 15789 15790@geindex -S (gnatbind) 15791 15792@item @code{-S@emph{xxx}} 15793 15794Specifies the value to be used when detecting uninitialized scalar 15795objects with pragma Initialize_Scalars. 15796The @code{xxx} string specified with the switch is one of: 15797 15798 15799@itemize * 15800 15801@item 15802@code{in} for an invalid value. 15803 15804If zero is invalid for the discrete type in question, 15805then the scalar value is set to all zero bits. 15806For signed discrete types, the largest possible negative value of 15807the underlying scalar is set (i.e. a one bit followed by all zero bits). 15808For unsigned discrete types, the underlying scalar value is set to all 15809one bits. For floating-point types, a NaN value is set 15810(see body of package System.Scalar_Values for exact values). 15811 15812@item 15813@code{lo} for low value. 15814 15815If zero is invalid for the discrete type in question, 15816then the scalar value is set to all zero bits. 15817For signed discrete types, the largest possible negative value of 15818the underlying scalar is set (i.e. a one bit followed by all zero bits). 15819For unsigned discrete types, the underlying scalar value is set to all 15820zero bits. For floating-point, a small value is set 15821(see body of package System.Scalar_Values for exact values). 15822 15823@item 15824@code{hi} for high value. 15825 15826If zero is invalid for the discrete type in question, 15827then the scalar value is set to all one bits. 15828For signed discrete types, the largest possible positive value of 15829the underlying scalar is set (i.e. a zero bit followed by all one bits). 15830For unsigned discrete types, the underlying scalar value is set to all 15831one bits. For floating-point, a large value is set 15832(see body of package System.Scalar_Values for exact values). 15833 15834@item 15835@code{xx} for hex value (two hex digits). 15836 15837The underlying scalar is set to a value consisting of repeated bytes, whose 15838value corresponds to the given value. For example if @code{BF} is given, 15839then a 32-bit scalar value will be set to the bit patterm @code{16#BFBFBFBF#}. 15840@end itemize 15841 15842@geindex GNAT_INIT_SCALARS 15843 15844In addition, you can specify @code{-Sev} to indicate that the value is 15845to be set at run time. In this case, the program will look for an environment 15846variable of the form @code{GNAT_INIT_SCALARS=@emph{yy}}, where @code{yy} is one 15847of @code{in/lo/hi/@emph{xx}} with the same meanings as above. 15848If no environment variable is found, or if it does not have a valid value, 15849then the default is @code{in} (invalid values). 15850@end table 15851 15852@geindex -static (gnatbind) 15853 15854 15855@table @asis 15856 15857@item @code{-static} 15858 15859Link against a static GNAT run-time. 15860 15861@geindex -shared (gnatbind) 15862 15863@item @code{-shared} 15864 15865Link against a shared GNAT run-time when available. 15866 15867@geindex -t (gnatbind) 15868 15869@item @code{-t} 15870 15871Tolerate time stamp and other consistency errors. 15872 15873@geindex -T (gnatbind) 15874 15875@item @code{-T@emph{n}} 15876 15877Set the time slice value to @code{n} milliseconds. If the system supports 15878the specification of a specific time slice value, then the indicated value 15879is used. If the system does not support specific time slice values, but 15880does support some general notion of round-robin scheduling, then any 15881nonzero value will activate round-robin scheduling. 15882 15883A value of zero is treated specially. It turns off time 15884slicing, and in addition, indicates to the tasking run-time that the 15885semantics should match as closely as possible the Annex D 15886requirements of the Ada RM, and in particular sets the default 15887scheduling policy to @code{FIFO_Within_Priorities}. 15888 15889@geindex -u (gnatbind) 15890 15891@item @code{-u@emph{n}} 15892 15893Enable dynamic stack usage, with @code{n} results stored and displayed 15894at program termination. A result is generated when a task 15895terminates. Results that can't be stored are displayed on the fly, at 15896task termination. This option is currently not supported on Itanium 15897platforms. (See @ref{113,,Dynamic Stack Usage Analysis} for details.) 15898 15899@geindex -v (gnatbind) 15900 15901@item @code{-v} 15902 15903Verbose mode. Write error messages, header, summary output to 15904@code{stdout}. 15905 15906@geindex -V (gnatbind) 15907 15908@item @code{-V@emph{key}=@emph{value}} 15909 15910Store the given association of @code{key} to @code{value} in the bind environment. 15911Values stored this way can be retrieved at run time using 15912@code{GNAT.Bind_Environment}. 15913 15914@geindex -w (gnatbind) 15915 15916@item @code{-w@emph{x}} 15917 15918Warning mode; @code{x} = s/e for suppress/treat as error. 15919 15920@geindex -Wx (gnatbind) 15921 15922@item @code{-Wx@emph{e}} 15923 15924Override default wide character encoding for standard Text_IO files. 15925 15926@geindex -x (gnatbind) 15927 15928@item @code{-x} 15929 15930Exclude source files (check object consistency only). 15931 15932@geindex -xdr (gnatbind) 15933 15934@item @code{-xdr} 15935 15936Use the target-independent XDR protocol for stream oriented attributes 15937instead of the default implementation which is based on direct binary 15938representations and is therefore target-and endianness-dependent. 15939However it does not support 128-bit integer types and the exception 15940@code{Ada.IO_Exceptions.Device_Error} is raised if any attempt is made 15941at streaming 128-bit integer types with it. 15942 15943@geindex -Xnnn (gnatbind) 15944 15945@item @code{-X@emph{nnn}} 15946 15947Set default exit status value, normally 0 for POSIX compliance. 15948 15949@geindex -y (gnatbind) 15950 15951@item @code{-y} 15952 15953Enable leap seconds support in @code{Ada.Calendar} and its children. 15954 15955@geindex -z (gnatbind) 15956 15957@item @code{-z} 15958 15959No main subprogram. 15960@end table 15961 15962You may obtain this listing of switches by running @code{gnatbind} with 15963no arguments. 15964 15965@menu 15966* Consistency-Checking Modes:: 15967* Binder Error Message Control:: 15968* Elaboration Control:: 15969* Output Control:: 15970* Dynamic Allocation Control:: 15971* Binding with Non-Ada Main Programs:: 15972* Binding Programs with No Main Subprogram:: 15973 15974@end menu 15975 15976@node Consistency-Checking Modes,Binder Error Message Control,,Switches for gnatbind 15977@anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{115} 15978@subsubsection Consistency-Checking Modes 15979 15980 15981As described earlier, by default @code{gnatbind} checks 15982that object files are consistent with one another and are consistent 15983with any source files it can locate. The following switches control binder 15984access to sources. 15985 15986@quotation 15987 15988@geindex -s (gnatbind) 15989@end quotation 15990 15991 15992@table @asis 15993 15994@item @code{-s} 15995 15996Require source files to be present. In this mode, the binder must be 15997able to locate all source files that are referenced, in order to check 15998their consistency. In normal mode, if a source file cannot be located it 15999is simply ignored. If you specify this switch, a missing source 16000file is an error. 16001 16002@geindex -Wx (gnatbind) 16003 16004@item @code{-Wx@emph{e}} 16005 16006Override default wide character encoding for standard Text_IO files. 16007Normally the default wide character encoding method used for standard 16008[Wide_[Wide_]]Text_IO files is taken from the encoding specified for 16009the main source input (see description of switch 16010@code{-gnatWx} for the compiler). The 16011use of this switch for the binder (which has the same set of 16012possible arguments) overrides this default as specified. 16013 16014@geindex -x (gnatbind) 16015 16016@item @code{-x} 16017 16018Exclude source files. In this mode, the binder only checks that ALI 16019files are consistent with one another. Source files are not accessed. 16020The binder runs faster in this mode, and there is still a guarantee that 16021the resulting program is self-consistent. 16022If a source file has been edited since it was last compiled, and you 16023specify this switch, the binder will not detect that the object 16024file is out of date with respect to the source file. Note that this is the 16025mode that is automatically used by @code{gnatmake} because in this 16026case the checking against sources has already been performed by 16027@code{gnatmake} in the course of compilation (i.e., before binding). 16028@end table 16029 16030@node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind 16031@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{116}@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{117} 16032@subsubsection Binder Error Message Control 16033 16034 16035The following switches provide control over the generation of error 16036messages from the binder: 16037 16038@quotation 16039 16040@geindex -v (gnatbind) 16041@end quotation 16042 16043 16044@table @asis 16045 16046@item @code{-v} 16047 16048Verbose mode. In the normal mode, brief error messages are generated to 16049@code{stderr}. If this switch is present, a header is written 16050to @code{stdout} and any error messages are directed to @code{stdout}. 16051All that is written to @code{stderr} is a brief summary message. 16052 16053@geindex -b (gnatbind) 16054 16055@item @code{-b} 16056 16057Generate brief error messages to @code{stderr} even if verbose mode is 16058specified. This is relevant only when used with the 16059@code{-v} switch. 16060 16061@geindex -m (gnatbind) 16062 16063@item @code{-m@emph{n}} 16064 16065Limits the number of error messages to @code{n}, a decimal integer in the 16066range 1-999. The binder terminates immediately if this limit is reached. 16067 16068@geindex -M (gnatbind) 16069 16070@item @code{-M@emph{xxx}} 16071 16072Renames the generated main program from @code{main} to @code{xxx}. 16073This is useful in the case of some cross-building environments, where 16074the actual main program is separate from the one generated 16075by @code{gnatbind}. 16076 16077@geindex -ws (gnatbind) 16078 16079@geindex Warnings 16080 16081@item @code{-ws} 16082 16083Suppress all warning messages. 16084 16085@geindex -we (gnatbind) 16086 16087@item @code{-we} 16088 16089Treat any warning messages as fatal errors. 16090 16091@geindex -t (gnatbind) 16092 16093@geindex Time stamp checks 16094@geindex in binder 16095 16096@geindex Binder consistency checks 16097 16098@geindex Consistency checks 16099@geindex in binder 16100 16101@item @code{-t} 16102 16103The binder performs a number of consistency checks including: 16104 16105 16106@itemize * 16107 16108@item 16109Check that time stamps of a given source unit are consistent 16110 16111@item 16112Check that checksums of a given source unit are consistent 16113 16114@item 16115Check that consistent versions of @code{GNAT} were used for compilation 16116 16117@item 16118Check consistency of configuration pragmas as required 16119@end itemize 16120 16121Normally failure of such checks, in accordance with the consistency 16122requirements of the Ada Reference Manual, causes error messages to be 16123generated which abort the binder and prevent the output of a binder 16124file and subsequent link to obtain an executable. 16125 16126The @code{-t} switch converts these error messages 16127into warnings, so that 16128binding and linking can continue to completion even in the presence of such 16129errors. The result may be a failed link (due to missing symbols), or a 16130non-functional executable which has undefined semantics. 16131 16132@cartouche 16133@quotation Note 16134This means that @code{-t} should be used only in unusual situations, 16135with extreme care. 16136@end quotation 16137@end cartouche 16138@end table 16139 16140@node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind 16141@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{118}@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{111} 16142@subsubsection Elaboration Control 16143 16144 16145The following switches provide additional control over the elaboration 16146order. For further details see @ref{f,,Elaboration Order Handling in GNAT}. 16147 16148@geindex -f (gnatbind) 16149 16150 16151@table @asis 16152 16153@item @code{-f@emph{elab-order}} 16154 16155Force elaboration order. 16156 16157@code{elab-order} should be the name of a "forced elaboration order file", that 16158is, a text file containing library item names, one per line. A name of the 16159form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A 16160name of the form "some.unit%b" or "some.unit (body)" denotes the body of 16161Some.Unit. Each pair of lines is taken to mean that there is an elaboration 16162dependence of the second line on the first. For example, if the file 16163contains: 16164 16165@example 16166this (spec) 16167this (body) 16168that (spec) 16169that (body) 16170@end example 16171 16172then the spec of This will be elaborated before the body of This, and the 16173body of This will be elaborated before the spec of That, and the spec of That 16174will be elaborated before the body of That. The first and last of these three 16175dependences are already required by Ada rules, so this file is really just 16176forcing the body of This to be elaborated before the spec of That. 16177 16178The given order must be consistent with Ada rules, or else @code{gnatbind} will 16179give elaboration cycle errors. For example, if you say x (body) should be 16180elaborated before x (spec), there will be a cycle, because Ada rules require 16181x (spec) to be elaborated before x (body); you can't have the spec and body 16182both elaborated before each other. 16183 16184If you later add "with That;" to the body of This, there will be a cycle, in 16185which case you should erase either "this (body)" or "that (spec)" from the 16186above forced elaboration order file. 16187 16188Blank lines and Ada-style comments are ignored. Unit names that do not exist 16189in the program are ignored. Units in the GNAT predefined library are also 16190ignored. 16191@end table 16192 16193@geindex -p (gnatbind) 16194 16195 16196@table @asis 16197 16198@item @code{-p} 16199 16200Pessimistic elaboration order 16201 16202This switch is only applicable to the pre-20.x legacy elaboration models. 16203The post-20.x elaboration model uses a more informed approach of ordering 16204the units. 16205 16206Normally the binder attempts to choose an elaboration order that is likely to 16207minimize the likelihood of an elaboration order error resulting in raising a 16208@code{Program_Error} exception. This switch reverses the action of the binder, 16209and requests that it deliberately choose an order that is likely to maximize 16210the likelihood of an elaboration error. This is useful in ensuring 16211portability and avoiding dependence on accidental fortuitous elaboration 16212ordering. 16213 16214Normally it only makes sense to use the @code{-p} switch if dynamic 16215elaboration checking is used (@code{-gnatE} switch used for compilation). 16216This is because in the default static elaboration mode, all necessary 16217@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted. 16218These implicit pragmas are still respected by the binder in @code{-p} 16219mode, so a safe elaboration order is assured. 16220 16221Note that @code{-p} is not intended for production use; it is more for 16222debugging/experimental use. 16223@end table 16224 16225@node Output Control,Dynamic Allocation Control,Elaboration Control,Switches for gnatbind 16226@anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{119}@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{11a} 16227@subsubsection Output Control 16228 16229 16230The following switches allow additional control over the output 16231generated by the binder. 16232 16233@quotation 16234 16235@geindex -c (gnatbind) 16236@end quotation 16237 16238 16239@table @asis 16240 16241@item @code{-c} 16242 16243Check only. Do not generate the binder output file. In this mode the 16244binder performs all error checks but does not generate an output file. 16245 16246@geindex -e (gnatbind) 16247 16248@item @code{-e} 16249 16250Output complete list of elaboration-order dependencies, showing the 16251reason for each dependency. This output can be rather extensive but may 16252be useful in diagnosing problems with elaboration order. The output is 16253written to @code{stdout}. 16254 16255@geindex -h (gnatbind) 16256 16257@item @code{-h} 16258 16259Output usage information. The output is written to @code{stdout}. 16260 16261@geindex -K (gnatbind) 16262 16263@item @code{-K} 16264 16265Output linker options to @code{stdout}. Includes library search paths, 16266contents of pragmas Ident and Linker_Options, and libraries added 16267by @code{gnatbind}. 16268 16269@geindex -l (gnatbind) 16270 16271@item @code{-l} 16272 16273Output chosen elaboration order. The output is written to @code{stdout}. 16274 16275@geindex -O (gnatbind) 16276 16277@item @code{-O} 16278 16279Output full names of all the object files that must be linked to provide 16280the Ada component of the program. The output is written to @code{stdout}. 16281This list includes the files explicitly supplied and referenced by the user 16282as well as implicitly referenced run-time unit files. The latter are 16283omitted if the corresponding units reside in shared libraries. The 16284directory names for the run-time units depend on the system configuration. 16285 16286@geindex -o (gnatbind) 16287 16288@item @code{-o @emph{file}} 16289 16290Set name of output file to @code{file} instead of the normal 16291@code{b~`mainprog}.adb` default. Note that @code{file} denote the Ada 16292binder generated body filename. 16293Note that if this option is used, then linking must be done manually. 16294It is not possible to use gnatlink in this case, since it cannot locate 16295the binder file. 16296 16297@geindex -r (gnatbind) 16298 16299@item @code{-r} 16300 16301Generate list of @code{pragma Restrictions} that could be applied to 16302the current unit. This is useful for code audit purposes, and also may 16303be used to improve code generation in some cases. 16304@end table 16305 16306@node Dynamic Allocation Control,Binding with Non-Ada Main Programs,Output Control,Switches for gnatbind 16307@anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{11b} 16308@subsubsection Dynamic Allocation Control 16309 16310 16311The heap control switches -- @code{-H32} and @code{-H64} -- 16312determine whether dynamic allocation uses 32-bit or 64-bit memory. 16313They only affect compiler-generated allocations via @code{__gnat_malloc}; 16314explicit calls to @code{malloc} and related functions from the C 16315run-time library are unaffected. 16316 16317 16318@table @asis 16319 16320@item @code{-H32} 16321 16322Allocate memory on 32-bit heap 16323 16324@item @code{-H64} 16325 16326Allocate memory on 64-bit heap. This is the default 16327unless explicitly overridden by a @code{'Size} clause on the access type. 16328@end table 16329 16330These switches are only effective on VMS platforms. 16331 16332@node Binding with Non-Ada Main Programs,Binding Programs with No Main Subprogram,Dynamic Allocation Control,Switches for gnatbind 16333@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{a0}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{11c} 16334@subsubsection Binding with Non-Ada Main Programs 16335 16336 16337The description so far has assumed that the main 16338program is in Ada, and that the task of the binder is to generate a 16339corresponding function @code{main} that invokes this Ada main 16340program. GNAT also supports the building of executable programs where 16341the main program is not in Ada, but some of the called routines are 16342written in Ada and compiled using GNAT (@ref{2c,,Mixed Language Programming}). 16343The following switch is used in this situation: 16344 16345@quotation 16346 16347@geindex -n (gnatbind) 16348@end quotation 16349 16350 16351@table @asis 16352 16353@item @code{-n} 16354 16355No main program. The main program is not in Ada. 16356@end table 16357 16358In this case, most of the functions of the binder are still required, 16359but instead of generating a main program, the binder generates a file 16360containing the following callable routines: 16361 16362@quotation 16363 16364@geindex adainit 16365 16366 16367@table @asis 16368 16369@item @code{adainit} 16370 16371You must call this routine to initialize the Ada part of the program by 16372calling the necessary elaboration routines. A call to @code{adainit} is 16373required before the first call to an Ada subprogram. 16374 16375Note that it is assumed that the basic execution environment must be setup 16376to be appropriate for Ada execution at the point where the first Ada 16377subprogram is called. In particular, if the Ada code will do any 16378floating-point operations, then the FPU must be setup in an appropriate 16379manner. For the case of the x86, for example, full precision mode is 16380required. The procedure GNAT.Float_Control.Reset may be used to ensure 16381that the FPU is in the right state. 16382@end table 16383 16384@geindex adafinal 16385 16386 16387@table @asis 16388 16389@item @code{adafinal} 16390 16391You must call this routine to perform any library-level finalization 16392required by the Ada subprograms. A call to @code{adafinal} is required 16393after the last call to an Ada subprogram, and before the program 16394terminates. 16395@end table 16396@end quotation 16397 16398@geindex -n (gnatbind) 16399 16400@geindex Binder 16401@geindex multiple input files 16402 16403If the @code{-n} switch 16404is given, more than one ALI file may appear on 16405the command line for @code{gnatbind}. The normal @code{closure} 16406calculation is performed for each of the specified units. Calculating 16407the closure means finding out the set of units involved by tracing 16408@emph{with} references. The reason it is necessary to be able to 16409specify more than one ALI file is that a given program may invoke two or 16410more quite separate groups of Ada units. 16411 16412The binder takes the name of its output file from the last specified ALI 16413file, unless overridden by the use of the @code{-o file}. 16414 16415@geindex -o (gnatbind) 16416 16417The output is an Ada unit in source form that can be compiled with GNAT. 16418This compilation occurs automatically as part of the @code{gnatlink} 16419processing. 16420 16421Currently the GNAT run-time requires a FPU using 80 bits mode 16422precision. Under targets where this is not the default it is required to 16423call GNAT.Float_Control.Reset before using floating point numbers (this 16424include float computation, float input and output) in the Ada code. A 16425side effect is that this could be the wrong mode for the foreign code 16426where floating point computation could be broken after this call. 16427 16428@node Binding Programs with No Main Subprogram,,Binding with Non-Ada Main Programs,Switches for gnatbind 16429@anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{11d}@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{11e} 16430@subsubsection Binding Programs with No Main Subprogram 16431 16432 16433It is possible to have an Ada program which does not have a main 16434subprogram. This program will call the elaboration routines of all the 16435packages, then the finalization routines. 16436 16437The following switch is used to bind programs organized in this manner: 16438 16439@quotation 16440 16441@geindex -z (gnatbind) 16442@end quotation 16443 16444 16445@table @asis 16446 16447@item @code{-z} 16448 16449Normally the binder checks that the unit name given on the command line 16450corresponds to a suitable main subprogram. When this switch is used, 16451a list of ALI files can be given, and the execution of the program 16452consists of elaboration of these units in an appropriate order. Note 16453that the default wide character encoding method for standard Text_IO 16454files is always set to Brackets if this switch is set (you can use 16455the binder switch 16456@code{-Wx} to override this default). 16457@end table 16458 16459@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind 16460@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{11f}@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{120} 16461@subsection Command-Line Access 16462 16463 16464The package @code{Ada.Command_Line} provides access to the command-line 16465arguments and program name. In order for this interface to operate 16466correctly, the two variables 16467 16468@example 16469int gnat_argc; 16470char **gnat_argv; 16471@end example 16472 16473@geindex gnat_argv 16474 16475@geindex gnat_argc 16476 16477are declared in one of the GNAT library routines. These variables must 16478be set from the actual @code{argc} and @code{argv} values passed to the 16479main program. With no @emph{n} present, @code{gnatbind} 16480generates the C main program to automatically set these variables. 16481If the @emph{n} switch is used, there is no automatic way to 16482set these variables. If they are not set, the procedures in 16483@code{Ada.Command_Line} will not be available, and any attempt to use 16484them will raise @code{Constraint_Error}. If command line access is 16485required, your main program must set @code{gnat_argc} and 16486@code{gnat_argv} from the @code{argc} and @code{argv} values passed to 16487it. 16488 16489@node Search Paths for gnatbind,Examples of gnatbind Usage,Command-Line Access,Binding with gnatbind 16490@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{76}@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{121} 16491@subsection Search Paths for @code{gnatbind} 16492 16493 16494The binder takes the name of an ALI file as its argument and needs to 16495locate source files as well as other ALI files to verify object consistency. 16496 16497For source files, it follows exactly the same search rules as @code{gcc} 16498(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). For ALI files the 16499directories searched are: 16500 16501 16502@itemize * 16503 16504@item 16505The directory containing the ALI file named in the command line, unless 16506the switch @code{-I-} is specified. 16507 16508@item 16509All directories specified by @code{-I} 16510switches on the @code{gnatbind} 16511command line, in the order given. 16512 16513@geindex ADA_PRJ_OBJECTS_FILE 16514 16515@item 16516Each of the directories listed in the text file whose name is given 16517by the 16518@geindex ADA_PRJ_OBJECTS_FILE 16519@geindex environment variable; ADA_PRJ_OBJECTS_FILE 16520@code{ADA_PRJ_OBJECTS_FILE} environment variable. 16521 16522@geindex ADA_PRJ_OBJECTS_FILE 16523@geindex environment variable; ADA_PRJ_OBJECTS_FILE 16524@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the gnat 16525driver when project files are used. It should not normally be set 16526by other means. 16527 16528@geindex ADA_OBJECTS_PATH 16529 16530@item 16531Each of the directories listed in the value of the 16532@geindex ADA_OBJECTS_PATH 16533@geindex environment variable; ADA_OBJECTS_PATH 16534@code{ADA_OBJECTS_PATH} environment variable. 16535Construct this value 16536exactly as the 16537@geindex PATH 16538@geindex environment variable; PATH 16539@code{PATH} environment variable: a list of directory 16540names separated by colons (semicolons when working with the NT version 16541of GNAT). 16542 16543@item 16544The content of the @code{ada_object_path} file which is part of the GNAT 16545installation tree and is used to store standard libraries such as the 16546GNAT Run-Time Library (RTL) unless the switch @code{-nostdlib} is 16547specified. See @ref{71,,Installing a library} 16548@end itemize 16549 16550@geindex -I (gnatbind) 16551 16552@geindex -aI (gnatbind) 16553 16554@geindex -aO (gnatbind) 16555 16556In the binder the switch @code{-I} 16557is used to specify both source and 16558library file paths. Use @code{-aI} 16559instead if you want to specify 16560source paths only, and @code{-aO} 16561if you want to specify library paths 16562only. This means that for the binder 16563@code{-I@emph{dir}} is equivalent to 16564@code{-aI@emph{dir}} 16565@code{-aO`@emph{dir}}. 16566The binder generates the bind file (a C language source file) in the 16567current working directory. 16568 16569@geindex Ada 16570 16571@geindex System 16572 16573@geindex Interfaces 16574 16575@geindex GNAT 16576 16577The packages @code{Ada}, @code{System}, and @code{Interfaces} and their 16578children make up the GNAT Run-Time Library, together with the package 16579GNAT and its children, which contain a set of useful additional 16580library functions provided by GNAT. The sources for these units are 16581needed by the compiler and are kept together in one directory. The ALI 16582files and object files generated by compiling the RTL are needed by the 16583binder and the linker and are kept together in one directory, typically 16584different from the directory containing the sources. In a normal 16585installation, you need not specify these directory names when compiling 16586or binding. Either the environment variables or the built-in defaults 16587cause these files to be found. 16588 16589Besides simplifying access to the RTL, a major use of search paths is 16590in compiling sources from multiple directories. This can make 16591development environments much more flexible. 16592 16593@node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind 16594@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{123} 16595@subsection Examples of @code{gnatbind} Usage 16596 16597 16598Here are some examples of @code{gnatbind} invovations: 16599 16600@quotation 16601 16602@example 16603gnatbind hello 16604@end example 16605 16606The main program @code{Hello} (source program in @code{hello.adb}) is 16607bound using the standard switch settings. The generated main program is 16608@code{b~hello.adb}. This is the normal, default use of the binder. 16609 16610@example 16611gnatbind hello -o mainprog.adb 16612@end example 16613 16614The main program @code{Hello} (source program in @code{hello.adb}) is 16615bound using the standard switch settings. The generated main program is 16616@code{mainprog.adb} with the associated spec in 16617@code{mainprog.ads}. Note that you must specify the body here not the 16618spec. Note that if this option is used, then linking must be done manually, 16619since gnatlink will not be able to find the generated file. 16620@end quotation 16621 16622@node Linking with gnatlink,Using the GNU make Utility,Binding with gnatbind,Building Executable Programs with GNAT 16623@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{124}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{c9} 16624@section Linking with @code{gnatlink} 16625 16626 16627@geindex gnatlink 16628 16629This chapter discusses @code{gnatlink}, a tool that links 16630an Ada program and builds an executable file. This utility 16631invokes the system linker (via the @code{gcc} command) 16632with a correct list of object files and library references. 16633@code{gnatlink} automatically determines the list of files and 16634references for the Ada part of a program. It uses the binder file 16635generated by the @code{gnatbind} to determine this list. 16636 16637@menu 16638* Running gnatlink:: 16639* Switches for gnatlink:: 16640 16641@end menu 16642 16643@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink 16644@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{125}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{126} 16645@subsection Running @code{gnatlink} 16646 16647 16648The form of the @code{gnatlink} command is 16649 16650@example 16651$ gnatlink [ switches ] mainprog [.ali] 16652 [ non-Ada objects ] [ linker options ] 16653@end example 16654 16655The arguments of @code{gnatlink} (switches, main @code{ALI} file, 16656non-Ada objects 16657or linker options) may be in any order, provided that no non-Ada object may 16658be mistaken for a main @code{ALI} file. 16659Any file name @code{F} without the @code{.ali} 16660extension will be taken as the main @code{ALI} file if a file exists 16661whose name is the concatenation of @code{F} and @code{.ali}. 16662 16663@code{mainprog.ali} references the ALI file of the main program. 16664The @code{.ali} extension of this file can be omitted. From this 16665reference, @code{gnatlink} locates the corresponding binder file 16666@code{b~mainprog.adb} and, using the information in this file along 16667with the list of non-Ada objects and linker options, constructs a 16668linker command file to create the executable. 16669 16670The arguments other than the @code{gnatlink} switches and the main 16671@code{ALI} file are passed to the linker uninterpreted. 16672They typically include the names of 16673object files for units written in other languages than Ada and any library 16674references required to resolve references in any of these foreign language 16675units, or in @code{Import} pragmas in any Ada units. 16676 16677@code{linker options} is an optional list of linker specific 16678switches. 16679The default linker called by gnatlink is @code{gcc} which in 16680turn calls the appropriate system linker. 16681 16682One useful option for the linker is @code{-s}: it reduces the size of the 16683executable by removing all symbol table and relocation information from the 16684executable. 16685 16686Standard options for the linker such as @code{-lmy_lib} or 16687@code{-Ldir} can be added as is. 16688For options that are not recognized by 16689@code{gcc} as linker options, use the @code{gcc} switches 16690@code{-Xlinker} or @code{-Wl,}. 16691 16692Refer to the GCC documentation for 16693details. 16694 16695Here is an example showing how to generate a linker map: 16696 16697@example 16698$ gnatlink my_prog -Wl,-Map,MAPFILE 16699@end example 16700 16701Using @code{linker options} it is possible to set the program stack and 16702heap size. 16703See @ref{127,,Setting Stack Size from gnatlink} and 16704@ref{128,,Setting Heap Size from gnatlink}. 16705 16706@code{gnatlink} determines the list of objects required by the Ada 16707program and prepends them to the list of objects passed to the linker. 16708@code{gnatlink} also gathers any arguments set by the use of 16709@code{pragma Linker_Options} and adds them to the list of arguments 16710presented to the linker. 16711 16712@node Switches for gnatlink,,Running gnatlink,Linking with gnatlink 16713@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{129}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{12a} 16714@subsection Switches for @code{gnatlink} 16715 16716 16717The following switches are available with the @code{gnatlink} utility: 16718 16719@geindex --version (gnatlink) 16720 16721 16722@table @asis 16723 16724@item @code{--version} 16725 16726Display Copyright and version, then exit disregarding all other options. 16727@end table 16728 16729@geindex --help (gnatlink) 16730 16731 16732@table @asis 16733 16734@item @code{--help} 16735 16736If @code{--version} was not used, display usage, then exit disregarding 16737all other options. 16738@end table 16739 16740@geindex Command line length 16741 16742@geindex -f (gnatlink) 16743 16744 16745@table @asis 16746 16747@item @code{-f} 16748 16749On some targets, the command line length is limited, and @code{gnatlink} 16750will generate a separate file for the linker if the list of object files 16751is too long. 16752The @code{-f} switch forces this file 16753to be generated even if 16754the limit is not exceeded. This is useful in some cases to deal with 16755special situations where the command line length is exceeded. 16756@end table 16757 16758@geindex Debugging information 16759@geindex including 16760 16761@geindex -g (gnatlink) 16762 16763 16764@table @asis 16765 16766@item @code{-g} 16767 16768The option to include debugging information causes the Ada bind file (in 16769other words, @code{b~mainprog.adb}) to be compiled with @code{-g}. 16770In addition, the binder does not delete the @code{b~mainprog.adb}, 16771@code{b~mainprog.o} and @code{b~mainprog.ali} files. 16772Without @code{-g}, the binder removes these files by default. 16773@end table 16774 16775@geindex -n (gnatlink) 16776 16777 16778@table @asis 16779 16780@item @code{-n} 16781 16782Do not compile the file generated by the binder. This may be used when 16783a link is rerun with different options, but there is no need to recompile 16784the binder file. 16785@end table 16786 16787@geindex -v (gnatlink) 16788 16789 16790@table @asis 16791 16792@item @code{-v} 16793 16794Verbose mode. Causes additional information to be output, including a full 16795list of the included object files. 16796This switch option is most useful when you want 16797to see what set of object files are being used in the link step. 16798@end table 16799 16800@geindex -v -v (gnatlink) 16801 16802 16803@table @asis 16804 16805@item @code{-v -v} 16806 16807Very verbose mode. Requests that the compiler operate in verbose mode when 16808it compiles the binder file, and that the system linker run in verbose mode. 16809@end table 16810 16811@geindex -o (gnatlink) 16812 16813 16814@table @asis 16815 16816@item @code{-o @emph{exec-name}} 16817 16818@code{exec-name} specifies an alternate name for the generated 16819executable program. If this switch is omitted, the executable has the same 16820name as the main unit. For example, @code{gnatlink try.ali} creates 16821an executable called @code{try}. 16822@end table 16823 16824@geindex -B (gnatlink) 16825 16826 16827@table @asis 16828 16829@item @code{-B@emph{dir}} 16830 16831Load compiler executables (for example, @code{gnat1}, the Ada compiler) 16832from @code{dir} instead of the default location. Only use this switch 16833when multiple versions of the GNAT compiler are available. 16834See the @code{Directory Options} section in @cite{The_GNU_Compiler_Collection} 16835for further details. You would normally use the @code{-b} or 16836@code{-V} switch instead. 16837@end table 16838 16839@geindex -M (gnatlink) 16840 16841 16842@table @asis 16843 16844@item @code{-M} 16845 16846When linking an executable, create a map file. The name of the map file 16847has the same name as the executable with extension ".map". 16848@end table 16849 16850@geindex -M= (gnatlink) 16851 16852 16853@table @asis 16854 16855@item @code{-M=@emph{mapfile}} 16856 16857When linking an executable, create a map file. The name of the map file is 16858@code{mapfile}. 16859@end table 16860 16861@geindex --GCC=compiler_name (gnatlink) 16862 16863 16864@table @asis 16865 16866@item @code{--GCC=@emph{compiler_name}} 16867 16868Program used for compiling the binder file. The default is 16869@code{gcc}. You need to use quotes around @code{compiler_name} if 16870@code{compiler_name} contains spaces or other separator characters. 16871As an example @code{--GCC="foo -x -y"} will instruct @code{gnatlink} to 16872use @code{foo -x -y} as your compiler. Note that switch @code{-c} is always 16873inserted after your command name. Thus in the above example the compiler 16874command that will be used by @code{gnatlink} will be @code{foo -c -x -y}. 16875A limitation of this syntax is that the name and path name of the executable 16876itself must not include any embedded spaces. If the compiler executable is 16877different from the default one (gcc or <prefix>-gcc), then the back-end 16878switches in the ALI file are not used to compile the binder generated source. 16879For example, this is the case with @code{--GCC="foo -x -y"}. But the back end 16880switches will be used for @code{--GCC="gcc -gnatv"}. If several 16881@code{--GCC=compiler_name} are used, only the last @code{compiler_name} 16882is taken into account. However, all the additional switches are also taken 16883into account. Thus, 16884@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to 16885@code{--GCC="bar -x -y -z -t"}. 16886@end table 16887 16888@geindex --LINK= (gnatlink) 16889 16890 16891@table @asis 16892 16893@item @code{--LINK=@emph{name}} 16894 16895@code{name} is the name of the linker to be invoked. This is especially 16896useful in mixed language programs since languages such as C++ require 16897their own linker to be used. When this switch is omitted, the default 16898name for the linker is @code{gcc}. When this switch is used, the 16899specified linker is called instead of @code{gcc} with exactly the same 16900parameters that would have been passed to @code{gcc} so if the desired 16901linker requires different parameters it is necessary to use a wrapper 16902script that massages the parameters before invoking the real linker. It 16903may be useful to control the exact invocation by using the verbose 16904switch. 16905@end table 16906 16907@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT 16908@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{70}@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{12b} 16909@section Using the GNU @code{make} Utility 16910 16911 16912@geindex make (GNU) 16913@geindex GNU make 16914 16915This chapter offers some examples of makefiles that solve specific 16916problems. It does not explain how to write a makefile, nor does it try to replace the 16917@code{gnatmake} utility (@ref{c6,,Building with gnatmake}). 16918 16919All the examples in this section are specific to the GNU version of 16920make. Although @code{make} is a standard utility, and the basic language 16921is the same, these examples use some advanced features found only in 16922@code{GNU make}. 16923 16924@menu 16925* Using gnatmake in a Makefile:: 16926* Automatically Creating a List of Directories:: 16927* Generating the Command Line Switches:: 16928* Overcoming Command Line Length Limits:: 16929 16930@end menu 16931 16932@node Using gnatmake in a Makefile,Automatically Creating a List of Directories,,Using the GNU make Utility 16933@anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{12d} 16934@subsection Using gnatmake in a Makefile 16935 16936 16937@c index makefile (GNU make) 16938 16939Complex project organizations can be handled in a very powerful way by 16940using GNU make combined with gnatmake. For instance, here is a Makefile 16941which allows you to build each subsystem of a big project into a separate 16942shared library. Such a makefile allows you to significantly reduce the link 16943time of very big applications while maintaining full coherence at 16944each step of the build process. 16945 16946The list of dependencies are handled automatically by 16947@code{gnatmake}. The Makefile is simply used to call gnatmake in each of 16948the appropriate directories. 16949 16950Note that you should also read the example on how to automatically 16951create the list of directories 16952(@ref{12e,,Automatically Creating a List of Directories}) 16953which might help you in case your project has a lot of subdirectories. 16954 16955@example 16956## This Makefile is intended to be used with the following directory 16957## configuration: 16958## - The sources are split into a series of csc (computer software components) 16959## Each of these csc is put in its own directory. 16960## Their name are referenced by the directory names. 16961## They will be compiled into shared library (although this would also work 16962## with static libraries 16963## - The main program (and possibly other packages that do not belong to any 16964## csc is put in the top level directory (where the Makefile is). 16965## toplevel_dir __ first_csc (sources) __ lib (will contain the library) 16966## \\_ second_csc (sources) __ lib (will contain the library) 16967## \\_ ... 16968## Although this Makefile is build for shared library, it is easy to modify 16969## to build partial link objects instead (modify the lines with -shared and 16970## gnatlink below) 16971## 16972## With this makefile, you can change any file in the system or add any new 16973## file, and everything will be recompiled correctly (only the relevant shared 16974## objects will be recompiled, and the main program will be re-linked). 16975 16976# The list of computer software component for your project. This might be 16977# generated automatically. 16978CSC_LIST=aa bb cc 16979 16980# Name of the main program (no extension) 16981MAIN=main 16982 16983# If we need to build objects with -fPIC, uncomment the following line 16984#NEED_FPIC=-fPIC 16985 16986# The following variable should give the directory containing libgnat.so 16987# You can get this directory through 'gnatls -v'. This is usually the last 16988# directory in the Object_Path. 16989GLIB=... 16990 16991# The directories for the libraries 16992# (This macro expands the list of CSC to the list of shared libraries, you 16993# could simply use the expanded form: 16994# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so 16995LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@} 16996 16997$@{MAIN@}: objects $@{LIB_DIR@} 16998 gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared 16999 gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@} 17000 17001objects:: 17002 # recompile the sources 17003 gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@} 17004 17005# Note: In a future version of GNAT, the following commands will be simplified 17006# by a new tool, gnatmlib 17007$@{LIB_DIR@}: 17008 mkdir -p $@{dir $@@ @} 17009 cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat 17010 cd $@{dir $@@ @} && cp -f ../*.ali . 17011 17012# The dependencies for the modules 17013# Note that we have to force the expansion of *.o, since in some cases 17014# make won't be able to do it itself. 17015aa/lib/libaa.so: $@{wildcard aa/*.o@} 17016bb/lib/libbb.so: $@{wildcard bb/*.o@} 17017cc/lib/libcc.so: $@{wildcard cc/*.o@} 17018 17019# Make sure all of the shared libraries are in the path before starting the 17020# program 17021run:: 17022 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@} 17023 17024clean:: 17025 $@{RM@} -rf $@{CSC_LIST:%=%/lib@} 17026 $@{RM@} $@{CSC_LIST:%=%/*.ali@} 17027 $@{RM@} $@{CSC_LIST:%=%/*.o@} 17028 $@{RM@} *.o *.ali $@{MAIN@} 17029@end example 17030 17031@node Automatically Creating a List of Directories,Generating the Command Line Switches,Using gnatmake in a Makefile,Using the GNU make Utility 17032@anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{12f}@anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{12e} 17033@subsection Automatically Creating a List of Directories 17034 17035 17036In most makefiles, you will have to specify a list of directories, and 17037store it in a variable. For small projects, it is often easier to 17038specify each of them by hand, since you then have full control over what 17039is the proper order for these directories, which ones should be 17040included. 17041 17042However, in larger projects, which might involve hundreds of 17043subdirectories, it might be more convenient to generate this list 17044automatically. 17045 17046The example below presents two methods. The first one, although less 17047general, gives you more control over the list. It involves wildcard 17048characters, that are automatically expanded by @code{make}. Its 17049shortcoming is that you need to explicitly specify some of the 17050organization of your project, such as for instance the directory tree 17051depth, whether some directories are found in a separate tree, etc. 17052 17053The second method is the most general one. It requires an external 17054program, called @code{find}, which is standard on all Unix systems. All 17055the directories found under a given root directory will be added to the 17056list. 17057 17058@example 17059# The examples below are based on the following directory hierarchy: 17060# All the directories can contain any number of files 17061# ROOT_DIRECTORY -> a -> aa -> aaa 17062# -> ab 17063# -> ac 17064# -> b -> ba -> baa 17065# -> bb 17066# -> bc 17067# This Makefile creates a variable called DIRS, that can be reused any time 17068# you need this list (see the other examples in this section) 17069 17070# The root of your project's directory hierarchy 17071ROOT_DIRECTORY=. 17072 17073#### 17074# First method: specify explicitly the list of directories 17075# This allows you to specify any subset of all the directories you need. 17076#### 17077 17078DIRS := a/aa/ a/ab/ b/ba/ 17079 17080#### 17081# Second method: use wildcards 17082# Note that the argument(s) to wildcard below should end with a '/'. 17083# Since wildcards also return file names, we have to filter them out 17084# to avoid duplicate directory names. 17085# We thus use make's `@w{`}dir`@w{`} and `@w{`}sort`@w{`} functions. 17086# It sets DIRs to the following value (note that the directories aaa and baa 17087# are not given, unless you change the arguments to wildcard). 17088# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ 17089#### 17090 17091DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/ 17092 $@{ROOT_DIRECTORY@}/*/*/@}@}@} 17093 17094#### 17095# Third method: use an external program 17096# This command is much faster if run on local disks, avoiding NFS slowdowns. 17097# This is the most complete command: it sets DIRs to the following value: 17098# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc 17099#### 17100 17101DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@} 17102@end example 17103 17104@node Generating the Command Line Switches,Overcoming Command Line Length Limits,Automatically Creating a List of Directories,Using the GNU make Utility 17105@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{130}@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{131} 17106@subsection Generating the Command Line Switches 17107 17108 17109Once you have created the list of directories as explained in the 17110previous section (@ref{12e,,Automatically Creating a List of Directories}), 17111you can easily generate the command line arguments to pass to gnatmake. 17112 17113For the sake of completeness, this example assumes that the source path 17114is not the same as the object path, and that you have two separate lists 17115of directories. 17116 17117@example 17118# see "Automatically creating a list of directories" to create 17119# these variables 17120SOURCE_DIRS= 17121OBJECT_DIRS= 17122 17123GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@} 17124GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@} 17125 17126all: 17127 gnatmake $@{GNATMAKE_SWITCHES@} main_unit 17128@end example 17129 17130@node Overcoming Command Line Length Limits,,Generating the Command Line Switches,Using the GNU make Utility 17131@anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{132}@anchor{gnat_ugn/building_executable_programs_with_gnat id52}@anchor{133} 17132@subsection Overcoming Command Line Length Limits 17133 17134 17135One problem that might be encountered on big projects is that many 17136operating systems limit the length of the command line. It is thus hard to give 17137gnatmake the list of source and object directories. 17138 17139This example shows how you can set up environment variables, which will 17140make @code{gnatmake} behave exactly as if the directories had been 17141specified on the command line, but have a much higher length limit (or 17142even none on most systems). 17143 17144It assumes that you have created a list of directories in your Makefile, 17145using one of the methods presented in 17146@ref{12e,,Automatically Creating a List of Directories}. 17147For the sake of completeness, we assume that the object 17148path (where the ALI files are found) is different from the sources patch. 17149 17150Note a small trick in the Makefile below: for efficiency reasons, we 17151create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are 17152expanded immediately by @code{make}. This way we overcome the standard 17153make behavior which is to expand the variables only when they are 17154actually used. 17155 17156On Windows, if you are using the standard Windows command shell, you must 17157replace colons with semicolons in the assignments to these variables. 17158 17159@example 17160# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH. 17161# This is the same thing as putting the -I arguments on the command line. 17162# (the equivalent of using -aI on the command line would be to define 17163# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH). 17164# You can of course have different values for these variables. 17165# 17166# Note also that we need to keep the previous values of these variables, since 17167# they might have been set before running 'make' to specify where the GNAT 17168# library is installed. 17169 17170# see "Automatically creating a list of directories" to create these 17171# variables 17172SOURCE_DIRS= 17173OBJECT_DIRS= 17174 17175empty:= 17176space:=$@{empty@} $@{empty@} 17177SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@} 17178OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@} 17179ADA_INCLUDE_PATH += $@{SOURCE_LIST@} 17180ADA_OBJECTS_PATH += $@{OBJECT_LIST@} 17181export ADA_INCLUDE_PATH 17182export ADA_OBJECTS_PATH 17183 17184all: 17185 gnatmake main_unit 17186@end example 17187 17188@node GNAT Utility Programs,GNAT and Program Execution,Building Executable Programs with GNAT,Top 17189@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{134}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{b}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{135} 17190@chapter GNAT Utility Programs 17191 17192 17193This chapter describes a number of utility programs: 17194 17195 17196 17197@itemize * 17198 17199@item 17200@ref{136,,The File Cleanup Utility gnatclean} 17201 17202@item 17203@ref{137,,The GNAT Library Browser gnatls} 17204@end itemize 17205 17206Other GNAT utilities are described elsewhere in this manual: 17207 17208 17209@itemize * 17210 17211@item 17212@ref{42,,Handling Arbitrary File Naming Conventions with gnatname} 17213 17214@item 17215@ref{4c,,File Name Krunching with gnatkr} 17216 17217@item 17218@ref{1d,,Renaming Files with gnatchop} 17219 17220@item 17221@ref{8f,,Preprocessing with gnatprep} 17222@end itemize 17223 17224@menu 17225* The File Cleanup Utility gnatclean:: 17226* The GNAT Library Browser gnatls:: 17227 17228@end menu 17229 17230@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs 17231@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{138}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{136} 17232@section The File Cleanup Utility @code{gnatclean} 17233 17234 17235@geindex File cleanup tool 17236 17237@geindex gnatclean 17238 17239@code{gnatclean} is a tool that allows the deletion of files produced by the 17240compiler, binder and linker, including ALI files, object files, tree files, 17241expanded source files, library files, interface copy source files, binder 17242generated files and executable files. 17243 17244@menu 17245* Running gnatclean:: 17246* Switches for gnatclean:: 17247 17248@end menu 17249 17250@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean 17251@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{13a} 17252@subsection Running @code{gnatclean} 17253 17254 17255The @code{gnatclean} command has the form: 17256 17257@quotation 17258 17259@example 17260$ gnatclean switches names 17261@end example 17262@end quotation 17263 17264where @code{names} is a list of source file names. Suffixes @code{.ads} and 17265@code{adb} may be omitted. If a project file is specified using switch 17266@code{-P}, then @code{names} may be completely omitted. 17267 17268In normal mode, @code{gnatclean} delete the files produced by the compiler and, 17269if switch @code{-c} is not specified, by the binder and 17270the linker. In informative-only mode, specified by switch 17271@code{-n}, the list of files that would have been deleted in 17272normal mode is listed, but no file is actually deleted. 17273 17274@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean 17275@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{13b}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13c} 17276@subsection Switches for @code{gnatclean} 17277 17278 17279@code{gnatclean} recognizes the following switches: 17280 17281@geindex --version (gnatclean) 17282 17283 17284@table @asis 17285 17286@item @code{--version} 17287 17288Display copyright and version, then exit disregarding all other options. 17289@end table 17290 17291@geindex --help (gnatclean) 17292 17293 17294@table @asis 17295 17296@item @code{--help} 17297 17298If @code{--version} was not used, display usage, then exit disregarding 17299all other options. 17300 17301@item @code{--subdirs=@emph{subdir}} 17302 17303Actual object directory of each project file is the subdirectory subdir of the 17304object directory specified or defaulted in the project file. 17305 17306@item @code{--unchecked-shared-lib-imports} 17307 17308By default, shared library projects are not allowed to import static library 17309projects. When this switch is used on the command line, this restriction is 17310relaxed. 17311@end table 17312 17313@geindex -c (gnatclean) 17314 17315 17316@table @asis 17317 17318@item @code{-c} 17319 17320Only attempt to delete the files produced by the compiler, not those produced 17321by the binder or the linker. The files that are not to be deleted are library 17322files, interface copy files, binder generated files and executable files. 17323@end table 17324 17325@geindex -D (gnatclean) 17326 17327 17328@table @asis 17329 17330@item @code{-D @emph{dir}} 17331 17332Indicate that ALI and object files should normally be found in directory @code{dir}. 17333@end table 17334 17335@geindex -F (gnatclean) 17336 17337 17338@table @asis 17339 17340@item @code{-F} 17341 17342When using project files, if some errors or warnings are detected during 17343parsing and verbose mode is not in effect (no use of switch 17344-v), then error lines start with the full path name of the project 17345file, rather than its simple file name. 17346@end table 17347 17348@geindex -h (gnatclean) 17349 17350 17351@table @asis 17352 17353@item @code{-h} 17354 17355Output a message explaining the usage of @code{gnatclean}. 17356@end table 17357 17358@geindex -n (gnatclean) 17359 17360 17361@table @asis 17362 17363@item @code{-n} 17364 17365Informative-only mode. Do not delete any files. Output the list of the files 17366that would have been deleted if this switch was not specified. 17367@end table 17368 17369@geindex -P (gnatclean) 17370 17371 17372@table @asis 17373 17374@item @code{-P@emph{project}} 17375 17376Use project file @code{project}. Only one such switch can be used. 17377When cleaning a project file, the files produced by the compilation of the 17378immediate sources or inherited sources of the project files are to be 17379deleted. This is not depending on the presence or not of executable names 17380on the command line. 17381@end table 17382 17383@geindex -q (gnatclean) 17384 17385 17386@table @asis 17387 17388@item @code{-q} 17389 17390Quiet output. If there are no errors, do not output anything, except in 17391verbose mode (switch -v) or in informative-only mode 17392(switch -n). 17393@end table 17394 17395@geindex -r (gnatclean) 17396 17397 17398@table @asis 17399 17400@item @code{-r} 17401 17402When a project file is specified (using switch -P), 17403clean all imported and extended project files, recursively. If this switch 17404is not specified, only the files related to the main project file are to be 17405deleted. This switch has no effect if no project file is specified. 17406@end table 17407 17408@geindex -v (gnatclean) 17409 17410 17411@table @asis 17412 17413@item @code{-v} 17414 17415Verbose mode. 17416@end table 17417 17418@geindex -vP (gnatclean) 17419 17420 17421@table @asis 17422 17423@item @code{-vP@emph{x}} 17424 17425Indicates the verbosity of the parsing of GNAT project files. 17426@ref{cf,,Switches Related to Project Files}. 17427@end table 17428 17429@geindex -X (gnatclean) 17430 17431 17432@table @asis 17433 17434@item @code{-X@emph{name}=@emph{value}} 17435 17436Indicates that external variable @code{name} has the value @code{value}. 17437The Project Manager will use this value for occurrences of 17438@code{external(name)} when parsing the project file. 17439See @ref{cf,,Switches Related to Project Files}. 17440@end table 17441 17442@geindex -aO (gnatclean) 17443 17444 17445@table @asis 17446 17447@item @code{-aO@emph{dir}} 17448 17449When searching for ALI and object files, look in directory @code{dir}. 17450@end table 17451 17452@geindex -I (gnatclean) 17453 17454 17455@table @asis 17456 17457@item @code{-I@emph{dir}} 17458 17459Equivalent to @code{-aO@emph{dir}}. 17460@end table 17461 17462@geindex -I- (gnatclean) 17463 17464@geindex Source files 17465@geindex suppressing search 17466 17467 17468@table @asis 17469 17470@item @code{-I-} 17471 17472Do not look for ALI or object files in the directory 17473where @code{gnatclean} was invoked. 17474@end table 17475 17476@node The GNAT Library Browser gnatls,,The File Cleanup Utility gnatclean,GNAT Utility Programs 17477@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13d} 17478@section The GNAT Library Browser @code{gnatls} 17479 17480 17481@geindex Library browser 17482 17483@geindex gnatls 17484 17485@code{gnatls} is a tool that outputs information about compiled 17486units. It gives the relationship between objects, unit names and source 17487files. It can also be used to check the source dependencies of a unit 17488as well as various characteristics. 17489 17490@menu 17491* Running gnatls:: 17492* Switches for gnatls:: 17493* Example of gnatls Usage:: 17494 17495@end menu 17496 17497@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls 17498@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f} 17499@subsection Running @code{gnatls} 17500 17501 17502The @code{gnatls} command has the form 17503 17504@quotation 17505 17506@example 17507$ gnatls switches object_or_ali_file 17508@end example 17509@end quotation 17510 17511The main argument is the list of object or @code{ali} files 17512(see @ref{28,,The Ada Library Information Files}) 17513for which information is requested. 17514 17515In normal mode, without additional option, @code{gnatls} produces a 17516four-column listing. Each line represents information for a specific 17517object. The first column gives the full path of the object, the second 17518column gives the name of the principal unit in this object, the third 17519column gives the status of the source and the fourth column gives the 17520full path of the source representing this unit. 17521Here is a simple example of use: 17522 17523@quotation 17524 17525@example 17526$ gnatls *.o 17527./demo1.o demo1 DIF demo1.adb 17528./demo2.o demo2 OK demo2.adb 17529./hello.o h1 OK hello.adb 17530./instr-child.o instr.child MOK instr-child.adb 17531./instr.o instr OK instr.adb 17532./tef.o tef DIF tef.adb 17533./text_io_example.o text_io_example OK text_io_example.adb 17534./tgef.o tgef DIF tgef.adb 17535@end example 17536@end quotation 17537 17538The first line can be interpreted as follows: the main unit which is 17539contained in 17540object file @code{demo1.o} is demo1, whose main source is in 17541@code{demo1.adb}. Furthermore, the version of the source used for the 17542compilation of demo1 has been modified (DIF). Each source file has a status 17543qualifier which can be: 17544 17545 17546@table @asis 17547 17548@item @emph{OK (unchanged)} 17549 17550The version of the source file used for the compilation of the 17551specified unit corresponds exactly to the actual source file. 17552 17553@item @emph{MOK (slightly modified)} 17554 17555The version of the source file used for the compilation of the 17556specified unit differs from the actual source file but not enough to 17557require recompilation. If you use gnatmake with the option 17558@code{-m} (minimal recompilation), a file marked 17559MOK will not be recompiled. 17560 17561@item @emph{DIF (modified)} 17562 17563No version of the source found on the path corresponds to the source 17564used to build this object. 17565 17566@item @emph{??? (file not found)} 17567 17568No source file was found for this unit. 17569 17570@item @emph{HID (hidden, unchanged version not first on PATH)} 17571 17572The version of the source that corresponds exactly to the source used 17573for compilation has been found on the path but it is hidden by another 17574version of the same source that has been modified. 17575@end table 17576 17577@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls 17578@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{140}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{141} 17579@subsection Switches for @code{gnatls} 17580 17581 17582@code{gnatls} recognizes the following switches: 17583 17584@geindex --version (gnatls) 17585 17586 17587@table @asis 17588 17589@item @code{--version} 17590 17591Display copyright and version, then exit disregarding all other options. 17592@end table 17593 17594@geindex --help (gnatls) 17595 17596 17597@table @asis 17598 17599@item @code{--help} 17600 17601If @code{--version} was not used, display usage, then exit disregarding 17602all other options. 17603@end table 17604 17605@geindex -a (gnatls) 17606 17607 17608@table @asis 17609 17610@item @code{-a} 17611 17612Consider all units, including those of the predefined Ada library. 17613Especially useful with @code{-d}. 17614@end table 17615 17616@geindex -d (gnatls) 17617 17618 17619@table @asis 17620 17621@item @code{-d} 17622 17623List sources from which specified units depend on. 17624@end table 17625 17626@geindex -h (gnatls) 17627 17628 17629@table @asis 17630 17631@item @code{-h} 17632 17633Output the list of options. 17634@end table 17635 17636@geindex -o (gnatls) 17637 17638 17639@table @asis 17640 17641@item @code{-o} 17642 17643Only output information about object files. 17644@end table 17645 17646@geindex -s (gnatls) 17647 17648 17649@table @asis 17650 17651@item @code{-s} 17652 17653Only output information about source files. 17654@end table 17655 17656@geindex -u (gnatls) 17657 17658 17659@table @asis 17660 17661@item @code{-u} 17662 17663Only output information about compilation units. 17664@end table 17665 17666@geindex -files (gnatls) 17667 17668 17669@table @asis 17670 17671@item @code{-files=@emph{file}} 17672 17673Take as arguments the files listed in text file @code{file}. 17674Text file @code{file} may contain empty lines that are ignored. 17675Each nonempty line should contain the name of an existing file. 17676Several such switches may be specified simultaneously. 17677@end table 17678 17679@geindex -aO (gnatls) 17680 17681@geindex -aI (gnatls) 17682 17683@geindex -I (gnatls) 17684 17685@geindex -I- (gnatls) 17686 17687 17688@table @asis 17689 17690@item @code{-aO@emph{dir}}, @code{-aI@emph{dir}}, @code{-I@emph{dir}}, @code{-I-}, @code{-nostdinc} 17691 17692Source path manipulation. Same meaning as the equivalent @code{gnatmake} 17693flags (@ref{cd,,Switches for gnatmake}). 17694@end table 17695 17696@geindex -aP (gnatls) 17697 17698 17699@table @asis 17700 17701@item @code{-aP@emph{dir}} 17702 17703Add @code{dir} at the beginning of the project search dir. 17704@end table 17705 17706@geindex --RTS (gnatls) 17707 17708 17709@table @asis 17710 17711@item @code{--RTS=@emph{rts-path}} 17712 17713Specifies the default location of the runtime library. Same meaning as the 17714equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}). 17715@end table 17716 17717@geindex -v (gnatls) 17718 17719 17720@table @asis 17721 17722@item @code{-v} 17723 17724Verbose mode. Output the complete source, object and project paths. Do not use 17725the default column layout but instead use long format giving as much as 17726information possible on each requested units, including special 17727characteristics such as: 17728 17729 17730@itemize * 17731 17732@item 17733@emph{Preelaborable}: The unit is preelaborable in the Ada sense. 17734 17735@item 17736@emph{No_Elab_Code}: No elaboration code has been produced by the compiler for this unit. 17737 17738@item 17739@emph{Pure}: The unit is pure in the Ada sense. 17740 17741@item 17742@emph{Elaborate_Body}: The unit contains a pragma Elaborate_Body. 17743 17744@item 17745@emph{Remote_Types}: The unit contains a pragma Remote_Types. 17746 17747@item 17748@emph{Shared_Passive}: The unit contains a pragma Shared_Passive. 17749 17750@item 17751@emph{Predefined}: This unit is part of the predefined environment and cannot be modified 17752by the user. 17753 17754@item 17755@emph{Remote_Call_Interface}: The unit contains a pragma Remote_Call_Interface. 17756@end itemize 17757@end table 17758 17759@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls 17760@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{143} 17761@subsection Example of @code{gnatls} Usage 17762 17763 17764Example of using the verbose switch. Note how the source and 17765object paths are affected by the -I switch. 17766 17767@quotation 17768 17769@example 17770$ gnatls -v -I.. demo1.o 17771 17772GNATLS 5.03w (20041123-34) 17773Copyright 1997-2004 Free Software Foundation, Inc. 17774 17775Source Search Path: 17776 <Current_Directory> 17777 ../ 17778 /home/comar/local/adainclude/ 17779 17780Object Search Path: 17781 <Current_Directory> 17782 ../ 17783 /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ 17784 17785Project Search Path: 17786 <Current_Directory> 17787 /home/comar/local/lib/gnat/ 17788 17789./demo1.o 17790 Unit => 17791 Name => demo1 17792 Kind => subprogram body 17793 Flags => No_Elab_Code 17794 Source => demo1.adb modified 17795@end example 17796@end quotation 17797 17798The following is an example of use of the dependency list. 17799Note the use of the -s switch 17800which gives a straight list of source files. This can be useful for 17801building specialized scripts. 17802 17803@quotation 17804 17805@example 17806$ gnatls -d demo2.o 17807./demo2.o demo2 OK demo2.adb 17808 OK gen_list.ads 17809 OK gen_list.adb 17810 OK instr.ads 17811 OK instr-child.ads 17812 17813$ gnatls -d -s -a demo1.o 17814demo1.adb 17815/home/comar/local/adainclude/ada.ads 17816/home/comar/local/adainclude/a-finali.ads 17817/home/comar/local/adainclude/a-filico.ads 17818/home/comar/local/adainclude/a-stream.ads 17819/home/comar/local/adainclude/a-tags.ads 17820gen_list.ads 17821gen_list.adb 17822/home/comar/local/adainclude/gnat.ads 17823/home/comar/local/adainclude/g-io.ads 17824instr.ads 17825/home/comar/local/adainclude/system.ads 17826/home/comar/local/adainclude/s-exctab.ads 17827/home/comar/local/adainclude/s-finimp.ads 17828/home/comar/local/adainclude/s-finroo.ads 17829/home/comar/local/adainclude/s-secsta.ads 17830/home/comar/local/adainclude/s-stalib.ads 17831/home/comar/local/adainclude/s-stoele.ads 17832/home/comar/local/adainclude/s-stratt.ads 17833/home/comar/local/adainclude/s-tasoli.ads 17834/home/comar/local/adainclude/s-unstyp.ads 17835/home/comar/local/adainclude/unchconv.ads 17836@end example 17837@end quotation 17838 17839 17840 17841 17842 17843 17844 17845 17846@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit 17847 17848@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top 17849@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{144}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{145} 17850@chapter GNAT and Program Execution 17851 17852 17853This chapter covers several topics: 17854 17855 17856@itemize * 17857 17858@item 17859@ref{146,,Running and Debugging Ada Programs} 17860 17861@item 17862@ref{147,,Profiling} 17863 17864@item 17865@ref{148,,Improving Performance} 17866 17867@item 17868@ref{149,,Overflow Check Handling in GNAT} 17869 17870@item 17871@ref{14a,,Performing Dimensionality Analysis in GNAT} 17872 17873@item 17874@ref{14b,,Stack Related Facilities} 17875 17876@item 17877@ref{14c,,Memory Management Issues} 17878@end itemize 17879 17880@menu 17881* Running and Debugging Ada Programs:: 17882* Profiling:: 17883* Improving Performance:: 17884* Overflow Check Handling in GNAT:: 17885* Performing Dimensionality Analysis in GNAT:: 17886* Stack Related Facilities:: 17887* Memory Management Issues:: 17888 17889@end menu 17890 17891@node Running and Debugging Ada Programs,Profiling,,GNAT and Program Execution 17892@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{146}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{14d} 17893@section Running and Debugging Ada Programs 17894 17895 17896@geindex Debugging 17897 17898This section discusses how to debug Ada programs. 17899 17900An incorrect Ada program may be handled in three ways by the GNAT compiler: 17901 17902 17903@itemize * 17904 17905@item 17906The illegality may be a violation of the static semantics of Ada. In 17907that case GNAT diagnoses the constructs in the program that are illegal. 17908It is then a straightforward matter for the user to modify those parts of 17909the program. 17910 17911@item 17912The illegality may be a violation of the dynamic semantics of Ada. In 17913that case the program compiles and executes, but may generate incorrect 17914results, or may terminate abnormally with some exception. 17915 17916@item 17917When presented with a program that contains convoluted errors, GNAT 17918itself may terminate abnormally without providing full diagnostics on 17919the incorrect user program. 17920@end itemize 17921 17922@geindex Debugger 17923 17924@geindex gdb 17925 17926@menu 17927* The GNAT Debugger GDB:: 17928* Running GDB:: 17929* Introduction to GDB Commands:: 17930* Using Ada Expressions:: 17931* Calling User-Defined Subprograms:: 17932* Using the next Command in a Function:: 17933* Stopping When Ada Exceptions Are Raised:: 17934* Ada Tasks:: 17935* Debugging Generic Units:: 17936* Remote Debugging with gdbserver:: 17937* GNAT Abnormal Termination or Failure to Terminate:: 17938* Naming Conventions for GNAT Source Files:: 17939* Getting Internal Debugging Information:: 17940* Stack Traceback:: 17941* Pretty-Printers for the GNAT runtime:: 17942 17943@end menu 17944 17945@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs 17946@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{14e}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{14f} 17947@subsection The GNAT Debugger GDB 17948 17949 17950@code{GDB} is a general purpose, platform-independent debugger that 17951can be used to debug mixed-language programs compiled with @code{gcc}, 17952and in particular is capable of debugging Ada programs compiled with 17953GNAT. The latest versions of @code{GDB} are Ada-aware and can handle 17954complex Ada data structures. 17955 17956See @cite{Debugging with GDB}, 17957for full details on the usage of @code{GDB}, including a section on 17958its usage on programs. This manual should be consulted for full 17959details. The section that follows is a brief introduction to the 17960philosophy and use of @code{GDB}. 17961 17962When GNAT programs are compiled, the compiler optionally writes debugging 17963information into the generated object file, including information on 17964line numbers, and on declared types and variables. This information is 17965separate from the generated code. It makes the object files considerably 17966larger, but it does not add to the size of the actual executable that 17967will be loaded into memory, and has no impact on run-time performance. The 17968generation of debug information is triggered by the use of the 17969@code{-g} switch in the @code{gcc} or @code{gnatmake} command 17970used to carry out the compilations. It is important to emphasize that 17971the use of these options does not change the generated code. 17972 17973The debugging information is written in standard system formats that 17974are used by many tools, including debuggers and profilers. The format 17975of the information is typically designed to describe C types and 17976semantics, but GNAT implements a translation scheme which allows full 17977details about Ada types and variables to be encoded into these 17978standard C formats. Details of this encoding scheme may be found in 17979the file exp_dbug.ads in the GNAT source distribution. However, the 17980details of this encoding are, in general, of no interest to a user, 17981since @code{GDB} automatically performs the necessary decoding. 17982 17983When a program is bound and linked, the debugging information is 17984collected from the object files, and stored in the executable image of 17985the program. Again, this process significantly increases the size of 17986the generated executable file, but it does not increase the size of 17987the executable program itself. Furthermore, if this program is run in 17988the normal manner, it runs exactly as if the debug information were 17989not present, and takes no more actual memory. 17990 17991However, if the program is run under control of @code{GDB}, the 17992debugger is activated. The image of the program is loaded, at which 17993point it is ready to run. If a run command is given, then the program 17994will run exactly as it would have if @code{GDB} were not present. This 17995is a crucial part of the @code{GDB} design philosophy. @code{GDB} is 17996entirely non-intrusive until a breakpoint is encountered. If no 17997breakpoint is ever hit, the program will run exactly as it would if no 17998debugger were present. When a breakpoint is hit, @code{GDB} accesses 17999the debugging information and can respond to user commands to inspect 18000variables, and more generally to report on the state of execution. 18001 18002@node Running GDB,Introduction to GDB Commands,The GNAT Debugger GDB,Running and Debugging Ada Programs 18003@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151} 18004@subsection Running GDB 18005 18006 18007This section describes how to initiate the debugger. 18008 18009The debugger can be launched from a @code{GNAT Studio} menu or 18010directly from the command line. The description below covers the latter use. 18011All the commands shown can be used in the @code{GNAT Studio} debug console window, 18012but there are usually more GUI-based ways to achieve the same effect. 18013 18014The command to run @code{GDB} is 18015 18016@quotation 18017 18018@example 18019$ gdb program 18020@end example 18021@end quotation 18022 18023where @code{program} is the name of the executable file. This 18024activates the debugger and results in a prompt for debugger commands. 18025The simplest command is simply @code{run}, which causes the program to run 18026exactly as if the debugger were not present. The following section 18027describes some of the additional commands that can be given to @code{GDB}. 18028 18029@node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs 18030@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{152}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{153} 18031@subsection Introduction to GDB Commands 18032 18033 18034@code{GDB} contains a large repertoire of commands. 18035See @cite{Debugging with GDB} for extensive documentation on the use 18036of these commands, together with examples of their use. Furthermore, 18037the command @emph{help} invoked from within GDB activates a simple help 18038facility which summarizes the available commands and their options. 18039In this section we summarize a few of the most commonly 18040used commands to give an idea of what @code{GDB} is about. You should create 18041a simple program with debugging information and experiment with the use of 18042these @code{GDB} commands on the program as you read through the 18043following section. 18044 18045 18046@itemize * 18047 18048@item 18049 18050@table @asis 18051 18052@item @code{set args @emph{arguments}} 18053 18054The @emph{arguments} list above is a list of arguments to be passed to 18055the program on a subsequent run command, just as though the arguments 18056had been entered on a normal invocation of the program. The @code{set args} 18057command is not needed if the program does not require arguments. 18058@end table 18059 18060@item 18061 18062@table @asis 18063 18064@item @code{run} 18065 18066The @code{run} command causes execution of the program to start from 18067the beginning. If the program is already running, that is to say if 18068you are currently positioned at a breakpoint, then a prompt will ask 18069for confirmation that you want to abandon the current execution and 18070restart. 18071@end table 18072 18073@item 18074 18075@table @asis 18076 18077@item @code{breakpoint @emph{location}} 18078 18079The breakpoint command sets a breakpoint, that is to say a point at which 18080execution will halt and @code{GDB} will await further 18081commands. @emph{location} is 18082either a line number within a file, given in the format @code{file:linenumber}, 18083or it is the name of a subprogram. If you request that a breakpoint be set on 18084a subprogram that is overloaded, a prompt will ask you to specify on which of 18085those subprograms you want to breakpoint. You can also 18086specify that all of them should be breakpointed. If the program is run 18087and execution encounters the breakpoint, then the program 18088stops and @code{GDB} signals that the breakpoint was encountered by 18089printing the line of code before which the program is halted. 18090@end table 18091 18092@item 18093 18094@table @asis 18095 18096@item @code{catch exception @emph{name}} 18097 18098This command causes the program execution to stop whenever exception 18099@code{name} is raised. If @code{name} is omitted, then the execution is 18100suspended when any exception is raised. 18101@end table 18102 18103@item 18104 18105@table @asis 18106 18107@item @code{print @emph{expression}} 18108 18109This will print the value of the given expression. Most simple 18110Ada expression formats are properly handled by @code{GDB}, so the expression 18111can contain function calls, variables, operators, and attribute references. 18112@end table 18113 18114@item 18115 18116@table @asis 18117 18118@item @code{continue} 18119 18120Continues execution following a breakpoint, until the next breakpoint or the 18121termination of the program. 18122@end table 18123 18124@item 18125 18126@table @asis 18127 18128@item @code{step} 18129 18130Executes a single line after a breakpoint. If the next statement 18131is a subprogram call, execution continues into (the first statement of) 18132the called subprogram. 18133@end table 18134 18135@item 18136 18137@table @asis 18138 18139@item @code{next} 18140 18141Executes a single line. If this line is a subprogram call, executes and 18142returns from the call. 18143@end table 18144 18145@item 18146 18147@table @asis 18148 18149@item @code{list} 18150 18151Lists a few lines around the current source location. In practice, it 18152is usually more convenient to have a separate edit window open with the 18153relevant source file displayed. Successive applications of this command 18154print subsequent lines. The command can be given an argument which is a 18155line number, in which case it displays a few lines around the specified one. 18156@end table 18157 18158@item 18159 18160@table @asis 18161 18162@item @code{backtrace} 18163 18164Displays a backtrace of the call chain. This command is typically 18165used after a breakpoint has occurred, to examine the sequence of calls that 18166leads to the current breakpoint. The display includes one line for each 18167activation record (frame) corresponding to an active subprogram. 18168@end table 18169 18170@item 18171 18172@table @asis 18173 18174@item @code{up} 18175 18176At a breakpoint, @code{GDB} can display the values of variables local 18177to the current frame. The command @code{up} can be used to 18178examine the contents of other active frames, by moving the focus up 18179the stack, that is to say from callee to caller, one frame at a time. 18180@end table 18181 18182@item 18183 18184@table @asis 18185 18186@item @code{down} 18187 18188Moves the focus of @code{GDB} down from the frame currently being 18189examined to the frame of its callee (the reverse of the previous command), 18190@end table 18191 18192@item 18193 18194@table @asis 18195 18196@item @code{frame @emph{n}} 18197 18198Inspect the frame with the given number. The value 0 denotes the frame 18199of the current breakpoint, that is to say the top of the call stack. 18200@end table 18201 18202@item 18203 18204@table @asis 18205 18206@item @code{kill} 18207 18208Kills the child process in which the program is running under GDB. 18209This may be useful for several purposes: 18210 18211 18212@itemize * 18213 18214@item 18215It allows you to recompile and relink your program, since on many systems 18216you cannot regenerate an executable file while it is running in a process. 18217 18218@item 18219You can run your program outside the debugger, on systems that do not 18220permit executing a program outside GDB while breakpoints are set 18221within GDB. 18222 18223@item 18224It allows you to debug a core dump rather than a running process. 18225@end itemize 18226@end table 18227@end itemize 18228 18229The above list is a very short introduction to the commands that 18230@code{GDB} provides. Important additional capabilities, including conditional 18231breakpoints, the ability to execute command sequences on a breakpoint, 18232the ability to debug at the machine instruction level and many other 18233features are described in detail in @cite{Debugging with GDB}. 18234Note that most commands can be abbreviated 18235(for example, c for continue, bt for backtrace). 18236 18237@node Using Ada Expressions,Calling User-Defined Subprograms,Introduction to GDB Commands,Running and Debugging Ada Programs 18238@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155} 18239@subsection Using Ada Expressions 18240 18241 18242@geindex Ada expressions (in gdb) 18243 18244@code{GDB} supports a fairly large subset of Ada expression syntax, with some 18245extensions. The philosophy behind the design of this subset is 18246 18247@quotation 18248 18249 18250@itemize * 18251 18252@item 18253That @code{GDB} should provide basic literals and access to operations for 18254arithmetic, dereferencing, field selection, indexing, and subprogram calls, 18255leaving more sophisticated computations to subprograms written into the 18256program (which therefore may be called from @code{GDB}). 18257 18258@item 18259That type safety and strict adherence to Ada language restrictions 18260are not particularly relevant in a debugging context. 18261 18262@item 18263That brevity is important to the @code{GDB} user. 18264@end itemize 18265@end quotation 18266 18267Thus, for brevity, the debugger acts as if there were 18268implicit @code{with} and @code{use} clauses in effect for all user-written 18269packages, thus making it unnecessary to fully qualify most names with 18270their packages, regardless of context. Where this causes ambiguity, 18271@code{GDB} asks the user's intent. 18272 18273For details on the supported Ada syntax, see @cite{Debugging with GDB}. 18274 18275@node Calling User-Defined Subprograms,Using the next Command in a Function,Using Ada Expressions,Running and Debugging Ada Programs 18276@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{156}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{157} 18277@subsection Calling User-Defined Subprograms 18278 18279 18280An important capability of @code{GDB} is the ability to call user-defined 18281subprograms while debugging. This is achieved simply by entering 18282a subprogram call statement in the form: 18283 18284@quotation 18285 18286@example 18287call subprogram-name (parameters) 18288@end example 18289@end quotation 18290 18291The keyword @code{call} can be omitted in the normal case where the 18292@code{subprogram-name} does not coincide with any of the predefined 18293@code{GDB} commands. 18294 18295The effect is to invoke the given subprogram, passing it the 18296list of parameters that is supplied. The parameters can be expressions and 18297can include variables from the program being debugged. The 18298subprogram must be defined 18299at the library level within your program, and @code{GDB} will call the 18300subprogram within the environment of your program execution (which 18301means that the subprogram is free to access or even modify variables 18302within your program). 18303 18304The most important use of this facility is in allowing the inclusion of 18305debugging routines that are tailored to particular data structures 18306in your program. Such debugging routines can be written to provide a suitably 18307high-level description of an abstract type, rather than a low-level dump 18308of its physical layout. After all, the standard 18309@code{GDB print} command only knows the physical layout of your 18310types, not their abstract meaning. Debugging routines can provide information 18311at the desired semantic level and are thus enormously useful. 18312 18313For example, when debugging GNAT itself, it is crucial to have access to 18314the contents of the tree nodes used to represent the program internally. 18315But tree nodes are represented simply by an integer value (which in turn 18316is an index into a table of nodes). 18317Using the @code{print} command on a tree node would simply print this integer 18318value, which is not very useful. But the PN routine (defined in file 18319treepr.adb in the GNAT sources) takes a tree node as input, and displays 18320a useful high level representation of the tree node, which includes the 18321syntactic category of the node, its position in the source, the integers 18322that denote descendant nodes and parent node, as well as varied 18323semantic information. To study this example in more detail, you might want to 18324look at the body of the PN procedure in the stated file. 18325 18326Another useful application of this capability is to deal with situations of 18327complex data which are not handled suitably by GDB. For example, if you specify 18328Convention Fortran for a multi-dimensional array, GDB does not know that 18329the ordering of array elements has been switched and will not properly 18330address the array elements. In such a case, instead of trying to print the 18331elements directly from GDB, you can write a callable procedure that prints 18332the elements in the desired format. 18333 18334@node Using the next Command in a Function,Stopping When Ada Exceptions Are Raised,Calling User-Defined Subprograms,Running and Debugging Ada Programs 18335@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{158}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{159} 18336@subsection Using the @emph{next} Command in a Function 18337 18338 18339When you use the @code{next} command in a function, the current source 18340location will advance to the next statement as usual. A special case 18341arises in the case of a @code{return} statement. 18342 18343Part of the code for a return statement is the 'epilogue' of the function. 18344This is the code that returns to the caller. There is only one copy of 18345this epilogue code, and it is typically associated with the last return 18346statement in the function if there is more than one return. In some 18347implementations, this epilogue is associated with the first statement 18348of the function. 18349 18350The result is that if you use the @code{next} command from a return 18351statement that is not the last return statement of the function you 18352may see a strange apparent jump to the last return statement or to 18353the start of the function. You should simply ignore this odd jump. 18354The value returned is always that from the first return statement 18355that was stepped through. 18356 18357@node Stopping When Ada Exceptions Are Raised,Ada Tasks,Using the next Command in a Function,Running and Debugging Ada Programs 18358@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{15b} 18359@subsection Stopping When Ada Exceptions Are Raised 18360 18361 18362@geindex Exceptions (in gdb) 18363 18364You can set catchpoints that stop the program execution when your program 18365raises selected exceptions. 18366 18367 18368@itemize * 18369 18370@item 18371 18372@table @asis 18373 18374@item @code{catch exception} 18375 18376Set a catchpoint that stops execution whenever (any task in the) program 18377raises any exception. 18378@end table 18379 18380@item 18381 18382@table @asis 18383 18384@item @code{catch exception @emph{name}} 18385 18386Set a catchpoint that stops execution whenever (any task in the) program 18387raises the exception @emph{name}. 18388@end table 18389 18390@item 18391 18392@table @asis 18393 18394@item @code{catch exception unhandled} 18395 18396Set a catchpoint that stops executing whenever (any task in the) program 18397raises an exception for which there is no handler. 18398@end table 18399 18400@item 18401 18402@table @asis 18403 18404@item @code{info exceptions}, @code{info exceptions @emph{regexp}} 18405 18406The @code{info exceptions} command permits the user to examine all defined 18407exceptions within Ada programs. With a regular expression, @emph{regexp}, as 18408argument, prints out only those exceptions whose name matches @emph{regexp}. 18409@end table 18410@end itemize 18411 18412@geindex Tasks (in gdb) 18413 18414@node Ada Tasks,Debugging Generic Units,Stopping When Ada Exceptions Are Raised,Running and Debugging Ada Programs 18415@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d} 18416@subsection Ada Tasks 18417 18418 18419@code{GDB} allows the following task-related commands: 18420 18421 18422@itemize * 18423 18424@item 18425 18426@table @asis 18427 18428@item @code{info tasks} 18429 18430This command shows a list of current Ada tasks, as in the following example: 18431 18432@example 18433(gdb) info tasks 18434 ID TID P-ID Thread Pri State Name 18435 1 8088000 0 807e000 15 Child Activation Wait main_task 18436 2 80a4000 1 80ae000 15 Accept/Select Wait b 18437 3 809a800 1 80a4800 15 Child Activation Wait a 18438* 4 80ae800 3 80b8000 15 Running c 18439@end example 18440 18441In this listing, the asterisk before the first task indicates it to be the 18442currently running task. The first column lists the task ID that is used 18443to refer to tasks in the following commands. 18444@end table 18445@end itemize 18446 18447@geindex Breakpoints and tasks 18448 18449 18450@itemize * 18451 18452@item 18453@code{break`@w{`}*linespec* `@w{`}task} @emph{taskid}, @code{break} @emph{linespec} @code{task} @emph{taskid} @code{if} ... 18454 18455@quotation 18456 18457These commands are like the @code{break ... thread ...}. 18458@emph{linespec} specifies source lines. 18459 18460Use the qualifier @code{task @emph{taskid}} with a breakpoint command 18461to specify that you only want @code{GDB} to stop the program when a 18462particular Ada task reaches this breakpoint. @emph{taskid} is one of the 18463numeric task identifiers assigned by @code{GDB}, shown in the first 18464column of the @code{info tasks} display. 18465 18466If you do not specify @code{task @emph{taskid}} when you set a 18467breakpoint, the breakpoint applies to @emph{all} tasks of your 18468program. 18469 18470You can use the @code{task} qualifier on conditional breakpoints as 18471well; in this case, place @code{task @emph{taskid}} before the 18472breakpoint condition (before the @code{if}). 18473@end quotation 18474@end itemize 18475 18476@geindex Task switching (in gdb) 18477 18478 18479@itemize * 18480 18481@item 18482@code{task @emph{taskno}} 18483 18484@quotation 18485 18486This command allows switching to the task referred by @emph{taskno}. In 18487particular, this allows browsing of the backtrace of the specified 18488task. It is advisable to switch back to the original task before 18489continuing execution otherwise the scheduling of the program may be 18490perturbed. 18491@end quotation 18492@end itemize 18493 18494For more detailed information on the tasking support, 18495see @cite{Debugging with GDB}. 18496 18497@geindex Debugging Generic Units 18498 18499@geindex Generics 18500 18501@node Debugging Generic Units,Remote Debugging with gdbserver,Ada Tasks,Running and Debugging Ada Programs 18502@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f} 18503@subsection Debugging Generic Units 18504 18505 18506GNAT always uses code expansion for generic instantiation. This means that 18507each time an instantiation occurs, a complete copy of the original code is 18508made, with appropriate substitutions of formals by actuals. 18509 18510It is not possible to refer to the original generic entities in 18511@code{GDB}, but it is always possible to debug a particular instance of 18512a generic, by using the appropriate expanded names. For example, if we have 18513 18514@quotation 18515 18516@example 18517procedure g is 18518 18519 generic package k is 18520 procedure kp (v1 : in out integer); 18521 end k; 18522 18523 package body k is 18524 procedure kp (v1 : in out integer) is 18525 begin 18526 v1 := v1 + 1; 18527 end kp; 18528 end k; 18529 18530 package k1 is new k; 18531 package k2 is new k; 18532 18533 var : integer := 1; 18534 18535begin 18536 k1.kp (var); 18537 k2.kp (var); 18538 k1.kp (var); 18539 k2.kp (var); 18540end; 18541@end example 18542@end quotation 18543 18544Then to break on a call to procedure kp in the k2 instance, simply 18545use the command: 18546 18547@quotation 18548 18549@example 18550(gdb) break g.k2.kp 18551@end example 18552@end quotation 18553 18554When the breakpoint occurs, you can step through the code of the 18555instance in the normal manner and examine the values of local variables, as for 18556other units. 18557 18558@geindex Remote Debugging with gdbserver 18559 18560@node Remote Debugging with gdbserver,GNAT Abnormal Termination or Failure to Terminate,Debugging Generic Units,Running and Debugging Ada Programs 18561@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{160}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{161} 18562@subsection Remote Debugging with gdbserver 18563 18564 18565On platforms where gdbserver is supported, it is possible to use this tool 18566to debug your application remotely. This can be useful in situations 18567where the program needs to be run on a target host that is different 18568from the host used for development, particularly when the target has 18569a limited amount of resources (either CPU and/or memory). 18570 18571To do so, start your program using gdbserver on the target machine. 18572gdbserver then automatically suspends the execution of your program 18573at its entry point, waiting for a debugger to connect to it. The 18574following commands starts an application and tells gdbserver to 18575wait for a connection with the debugger on localhost port 4444. 18576 18577@quotation 18578 18579@example 18580$ gdbserver localhost:4444 program 18581Process program created; pid = 5685 18582Listening on port 4444 18583@end example 18584@end quotation 18585 18586Once gdbserver has started listening, we can tell the debugger to establish 18587a connection with this gdbserver, and then start the same debugging session 18588as if the program was being debugged on the same host, directly under 18589the control of GDB. 18590 18591@quotation 18592 18593@example 18594$ gdb program 18595(gdb) target remote targethost:4444 18596Remote debugging using targethost:4444 185970x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. 18598(gdb) b foo.adb:3 18599Breakpoint 1 at 0x401f0c: file foo.adb, line 3. 18600(gdb) continue 18601Continuing. 18602 18603Breakpoint 1, foo () at foo.adb:4 186044 end foo; 18605@end example 18606@end quotation 18607 18608It is also possible to use gdbserver to attach to an already running 18609program, in which case the execution of that program is simply suspended 18610until the connection between the debugger and gdbserver is established. 18611 18612For more information on how to use gdbserver, see the @emph{Using the gdbserver Program} 18613section in @cite{Debugging with GDB}. 18614GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux. 18615 18616@geindex Abnormal Termination or Failure to Terminate 18617 18618@node GNAT Abnormal Termination or Failure to Terminate,Naming Conventions for GNAT Source Files,Remote Debugging with gdbserver,Running and Debugging Ada Programs 18619@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163} 18620@subsection GNAT Abnormal Termination or Failure to Terminate 18621 18622 18623When presented with programs that contain serious errors in syntax 18624or semantics, 18625GNAT may on rare occasions experience problems in operation, such 18626as aborting with a 18627segmentation fault or illegal memory access, raising an internal 18628exception, terminating abnormally, or failing to terminate at all. 18629In such cases, you can activate 18630various features of GNAT that can help you pinpoint the construct in your 18631program that is the likely source of the problem. 18632 18633The following strategies are presented in increasing order of 18634difficulty, corresponding to your experience in using GNAT and your 18635familiarity with compiler internals. 18636 18637 18638@itemize * 18639 18640@item 18641Run @code{gcc} with the @code{-gnatf}. This first 18642switch causes all errors on a given line to be reported. In its absence, 18643only the first error on a line is displayed. 18644 18645The @code{-gnatdO} switch causes errors to be displayed as soon as they 18646are encountered, rather than after compilation is terminated. If GNAT 18647terminates prematurely or goes into an infinite loop, the last error 18648message displayed may help to pinpoint the culprit. 18649 18650@item 18651Run @code{gcc} with the @code{-v} (verbose) switch. In this 18652mode, @code{gcc} produces ongoing information about the progress of the 18653compilation and provides the name of each procedure as code is 18654generated. This switch allows you to find which Ada procedure was being 18655compiled when it encountered a code generation problem. 18656@end itemize 18657 18658@geindex -gnatdc switch 18659 18660 18661@itemize * 18662 18663@item 18664Run @code{gcc} with the @code{-gnatdc} switch. This is a GNAT specific 18665switch that does for the front-end what @code{-v} does 18666for the back end. The system prints the name of each unit, 18667either a compilation unit or nested unit, as it is being analyzed. 18668 18669@item 18670Finally, you can start 18671@code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the 18672front-end of GNAT, and can be run independently (normally it is just 18673called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you 18674would on a C program (but @ref{14e,,The GNAT Debugger GDB} for caveats). The 18675@code{where} command is the first line of attack; the variable 18676@code{lineno} (seen by @code{print lineno}), used by the second phase of 18677@code{gnat1} and by the @code{gcc} backend, indicates the source line at 18678which the execution stopped, and @code{input_file name} indicates the name of 18679the source file. 18680@end itemize 18681 18682@node Naming Conventions for GNAT Source Files,Getting Internal Debugging Information,GNAT Abnormal Termination or Failure to Terminate,Running and Debugging Ada Programs 18683@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{165} 18684@subsection Naming Conventions for GNAT Source Files 18685 18686 18687In order to examine the workings of the GNAT system, the following 18688brief description of its organization may be helpful: 18689 18690 18691@itemize * 18692 18693@item 18694Files with prefix @code{sc} contain the lexical scanner. 18695 18696@item 18697All files prefixed with @code{par} are components of the parser. The 18698numbers correspond to chapters of the Ada Reference Manual. For example, 18699parsing of select statements can be found in @code{par-ch9.adb}. 18700 18701@item 18702All files prefixed with @code{sem} perform semantic analysis. The 18703numbers correspond to chapters of the Ada standard. For example, all 18704issues involving context clauses can be found in @code{sem_ch10.adb}. In 18705addition, some features of the language require sufficient special processing 18706to justify their own semantic files: sem_aggr for aggregates, sem_disp for 18707dynamic dispatching, etc. 18708 18709@item 18710All files prefixed with @code{exp} perform normalization and 18711expansion of the intermediate representation (abstract syntax tree, or AST). 18712these files use the same numbering scheme as the parser and semantics files. 18713For example, the construction of record initialization procedures is done in 18714@code{exp_ch3.adb}. 18715 18716@item 18717The files prefixed with @code{bind} implement the binder, which 18718verifies the consistency of the compilation, determines an order of 18719elaboration, and generates the bind file. 18720 18721@item 18722The files @code{atree.ads} and @code{atree.adb} detail the low-level 18723data structures used by the front-end. 18724 18725@item 18726The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of 18727the abstract syntax tree as produced by the parser. 18728 18729@item 18730The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of 18731all entities, computed during semantic analysis. 18732 18733@item 18734Library management issues are dealt with in files with prefix 18735@code{lib}. 18736 18737@geindex Annex A (in Ada Reference Manual) 18738 18739@item 18740Ada files with the prefix @code{a-} are children of @code{Ada}, as 18741defined in Annex A. 18742 18743@geindex Annex B (in Ada reference Manual) 18744 18745@item 18746Files with prefix @code{i-} are children of @code{Interfaces}, as 18747defined in Annex B. 18748 18749@geindex System (package in Ada Reference Manual) 18750 18751@item 18752Files with prefix @code{s-} are children of @code{System}. This includes 18753both language-defined children and GNAT run-time routines. 18754 18755@geindex GNAT (package) 18756 18757@item 18758Files with prefix @code{g-} are children of @code{GNAT}. These are useful 18759general-purpose packages, fully documented in their specs. All 18760the other @code{.c} files are modifications of common @code{gcc} files. 18761@end itemize 18762 18763@node Getting Internal Debugging Information,Stack Traceback,Naming Conventions for GNAT Source Files,Running and Debugging Ada Programs 18764@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{167} 18765@subsection Getting Internal Debugging Information 18766 18767 18768Most compilers have internal debugging switches and modes. GNAT 18769does also, except GNAT internal debugging switches and modes are not 18770secret. A summary and full description of all the compiler and binder 18771debug flags are in the file @code{debug.adb}. You must obtain the 18772sources of the compiler to see the full detailed effects of these flags. 18773 18774The switches that print the source of the program (reconstructed from 18775the internal tree) are of general interest for user programs, as are the 18776options to print 18777the full internal tree, and the entity table (the symbol table 18778information). The reconstructed source provides a readable version of the 18779program after the front-end has completed analysis and expansion, 18780and is useful when studying the performance of specific constructs. 18781For example, constraint checks are indicated, complex aggregates 18782are replaced with loops and assignments, and tasking primitives 18783are replaced with run-time calls. 18784 18785@geindex traceback 18786 18787@geindex stack traceback 18788 18789@geindex stack unwinding 18790 18791@node Stack Traceback,Pretty-Printers for the GNAT runtime,Getting Internal Debugging Information,Running and Debugging Ada Programs 18792@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{169} 18793@subsection Stack Traceback 18794 18795 18796Traceback is a mechanism to display the sequence of subprogram calls that 18797leads to a specified execution point in a program. Often (but not always) 18798the execution point is an instruction at which an exception has been raised. 18799This mechanism is also known as @emph{stack unwinding} because it obtains 18800its information by scanning the run-time stack and recovering the activation 18801records of all active subprograms. Stack unwinding is one of the most 18802important tools for program debugging. 18803 18804The first entry stored in traceback corresponds to the deepest calling level, 18805that is to say the subprogram currently executing the instruction 18806from which we want to obtain the traceback. 18807 18808Note that there is no runtime performance penalty when stack traceback 18809is enabled, and no exception is raised during program execution. 18810 18811@geindex traceback 18812@geindex non-symbolic 18813 18814@menu 18815* Non-Symbolic Traceback:: 18816* Symbolic Traceback:: 18817 18818@end menu 18819 18820@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback 18821@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{16b} 18822@subsubsection Non-Symbolic Traceback 18823 18824 18825Note: this feature is not supported on all platforms. See 18826@code{GNAT.Traceback} spec in @code{g-traceb.ads} 18827for a complete list of supported platforms. 18828 18829@subsubheading Tracebacks From an Unhandled Exception 18830 18831 18832A runtime non-symbolic traceback is a list of addresses of call instructions. 18833To enable this feature you must use the @code{-E} 18834@code{gnatbind} option. With this option a stack traceback is stored as part 18835of exception information. You can retrieve this information using the 18836@code{addr2line} tool. 18837 18838Here is a simple example: 18839 18840@quotation 18841 18842@example 18843procedure STB is 18844 18845 procedure P1 is 18846 begin 18847 raise Constraint_Error; 18848 end P1; 18849 18850 procedure P2 is 18851 begin 18852 P1; 18853 end P2; 18854 18855begin 18856 P2; 18857end STB; 18858@end example 18859 18860@example 18861$ gnatmake stb -bargs -E 18862$ stb 18863 18864Execution terminated by unhandled exception 18865Exception name: CONSTRAINT_ERROR 18866Message: stb.adb:5 18867Call stack traceback locations: 188680x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 18869@end example 18870@end quotation 18871 18872As we see the traceback lists a sequence of addresses for the unhandled 18873exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to 18874guess that this exception come from procedure P1. To translate these 18875addresses into the source lines where the calls appear, the 18876@code{addr2line} tool, described below, is invaluable. The use of this tool 18877requires the program to be compiled with debug information. 18878 18879@quotation 18880 18881@example 18882$ gnatmake -g stb -bargs -E 18883$ stb 18884 18885Execution terminated by unhandled exception 18886Exception name: CONSTRAINT_ERROR 18887Message: stb.adb:5 18888Call stack traceback locations: 188890x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 18890 18891$ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 18892 0x4011f1 0x77e892a4 18893 1889400401373 at d:/stb/stb.adb:5 188950040138B at d:/stb/stb.adb:10 188960040139C at d:/stb/stb.adb:14 1889700401335 at d:/stb/b~stb.adb:104 18898004011C4 at /build/.../crt1.c:200 18899004011F1 at /build/.../crt1.c:222 1890077E892A4 in ?? at ??:0 18901@end example 18902@end quotation 18903 18904The @code{addr2line} tool has several other useful options: 18905 18906@quotation 18907 18908 18909@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 18910@item 18911 18912@code{--functions} 18913 18914@tab 18915 18916to get the function name corresponding to any location 18917 18918@item 18919 18920@code{--demangle=gnat} 18921 18922@tab 18923 18924to use the gnat decoding mode for the function names. 18925Note that for binutils version 2.9.x the option is 18926simply @code{--demangle}. 18927 18928@end multitable 18929 18930 18931@example 18932$ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b 18933 0x40139c 0x401335 0x4011c4 0x4011f1 18934 1893500401373 in stb.p1 at d:/stb/stb.adb:5 189360040138B in stb.p2 at d:/stb/stb.adb:10 189370040139C in stb at d:/stb/stb.adb:14 1893800401335 in main at d:/stb/b~stb.adb:104 18939004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 18940004011F1 in <mainCRTStartup> at /build/.../crt1.c:222 18941@end example 18942@end quotation 18943 18944From this traceback we can see that the exception was raised in 18945@code{stb.adb} at line 5, which was reached from a procedure call in 18946@code{stb.adb} at line 10, and so on. The @code{b~std.adb} is the binder file, 18947which contains the call to the main program. 18948@ref{10d,,Running gnatbind}. The remaining entries are assorted runtime routines, 18949and the output will vary from platform to platform. 18950 18951It is also possible to use @code{GDB} with these traceback addresses to debug 18952the program. For example, we can break at a given code location, as reported 18953in the stack traceback: 18954 18955@quotation 18956 18957@example 18958$ gdb -nw stb 18959@end example 18960@end quotation 18961 18962Furthermore, this feature is not implemented inside Windows DLL. Only 18963the non-symbolic traceback is reported in this case. 18964 18965@quotation 18966 18967@example 18968(gdb) break *0x401373 18969Breakpoint 1 at 0x401373: file stb.adb, line 5. 18970@end example 18971@end quotation 18972 18973It is important to note that the stack traceback addresses 18974do not change when debug information is included. This is particularly useful 18975because it makes it possible to release software without debug information (to 18976minimize object size), get a field report that includes a stack traceback 18977whenever an internal bug occurs, and then be able to retrieve the sequence 18978of calls with the same program compiled with debug information. 18979 18980@subsubheading Tracebacks From Exception Occurrences 18981 18982 18983Non-symbolic tracebacks are obtained by using the @code{-E} binder argument. 18984The stack traceback is attached to the exception information string, and can 18985be retrieved in an exception handler within the Ada program, by means of the 18986Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example: 18987 18988@quotation 18989 18990@example 18991with Ada.Text_IO; 18992with Ada.Exceptions; 18993 18994procedure STB is 18995 18996 use Ada; 18997 use Ada.Exceptions; 18998 18999 procedure P1 is 19000 K : Positive := 1; 19001 begin 19002 K := K - 1; 19003 exception 19004 when E : others => 19005 Text_IO.Put_Line (Exception_Information (E)); 19006 end P1; 19007 19008 procedure P2 is 19009 begin 19010 P1; 19011 end P2; 19012 19013begin 19014 P2; 19015end STB; 19016@end example 19017@end quotation 19018 19019This program will output: 19020 19021@quotation 19022 19023@example 19024$ stb 19025 19026Exception name: CONSTRAINT_ERROR 19027Message: stb.adb:12 19028Call stack traceback locations: 190290x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 19030@end example 19031@end quotation 19032 19033@subsubheading Tracebacks From Anywhere in a Program 19034 19035 19036It is also possible to retrieve a stack traceback from anywhere in a 19037program. For this you need to 19038use the @code{GNAT.Traceback} API. This package includes a procedure called 19039@code{Call_Chain} that computes a complete stack traceback, as well as useful 19040display procedures described below. It is not necessary to use the 19041@code{-E} @code{gnatbind} option in this case, because the stack traceback mechanism 19042is invoked explicitly. 19043 19044In the following example we compute a traceback at a specific location in 19045the program, and we display it using @code{GNAT.Debug_Utilities.Image} to 19046convert addresses to strings: 19047 19048@quotation 19049 19050@example 19051with Ada.Text_IO; 19052with GNAT.Traceback; 19053with GNAT.Debug_Utilities; 19054 19055procedure STB is 19056 19057 use Ada; 19058 use GNAT; 19059 use GNAT.Traceback; 19060 19061 procedure P1 is 19062 TB : Tracebacks_Array (1 .. 10); 19063 -- We are asking for a maximum of 10 stack frames. 19064 Len : Natural; 19065 -- Len will receive the actual number of stack frames returned. 19066 begin 19067 Call_Chain (TB, Len); 19068 19069 Text_IO.Put ("In STB.P1 : "); 19070 19071 for K in 1 .. Len loop 19072 Text_IO.Put (Debug_Utilities.Image (TB (K))); 19073 Text_IO.Put (' '); 19074 end loop; 19075 19076 Text_IO.New_Line; 19077 end P1; 19078 19079 procedure P2 is 19080 begin 19081 P1; 19082 end P2; 19083 19084begin 19085 P2; 19086end STB; 19087@end example 19088 19089@example 19090$ gnatmake -g stb 19091$ stb 19092 19093In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# 1909416#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# 19095@end example 19096@end quotation 19097 19098You can then get further information by invoking the @code{addr2line} 19099tool as described earlier (note that the hexadecimal addresses 19100need to be specified in C format, with a leading '0x'). 19101 19102@geindex traceback 19103@geindex symbolic 19104 19105@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback 19106@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d} 19107@subsubsection Symbolic Traceback 19108 19109 19110A symbolic traceback is a stack traceback in which procedure names are 19111associated with each code location. 19112 19113Note that this feature is not supported on all platforms. See 19114@code{GNAT.Traceback.Symbolic} spec in @code{g-trasym.ads} for a complete 19115list of currently supported platforms. 19116 19117Note that the symbolic traceback requires that the program be compiled 19118with debug information. If it is not compiled with debug information 19119only the non-symbolic information will be valid. 19120 19121@subsubheading Tracebacks From Exception Occurrences 19122 19123 19124Here is an example: 19125 19126@quotation 19127 19128@example 19129with Ada.Text_IO; 19130with GNAT.Traceback.Symbolic; 19131 19132procedure STB is 19133 19134 procedure P1 is 19135 begin 19136 raise Constraint_Error; 19137 end P1; 19138 19139 procedure P2 is 19140 begin 19141 P1; 19142 end P2; 19143 19144 procedure P3 is 19145 begin 19146 P2; 19147 end P3; 19148 19149begin 19150 P3; 19151exception 19152 when E : others => 19153 Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); 19154end STB; 19155@end example 19156 19157@example 19158$ gnatmake -g .\stb -bargs -E 19159$ stb 19160 191610040149F in stb.p1 at stb.adb:8 19162004014B7 in stb.p2 at stb.adb:13 19163004014CF in stb.p3 at stb.adb:18 19164004015DD in ada.stb at stb.adb:22 1916500401461 in main at b~stb.adb:168 19166004011C4 in __mingw_CRTStartup at crt1.c:200 19167004011F1 in mainCRTStartup at crt1.c:222 1916877E892A4 in ?? at ??:0 19169@end example 19170@end quotation 19171 19172In the above example the @code{.\} syntax in the @code{gnatmake} command 19173is currently required by @code{addr2line} for files that are in 19174the current working directory. 19175Moreover, the exact sequence of linker options may vary from platform 19176to platform. 19177The above @code{-largs} section is for Windows platforms. By contrast, 19178under Unix there is no need for the @code{-largs} section. 19179Differences across platforms are due to details of linker implementation. 19180 19181@subsubheading Tracebacks From Anywhere in a Program 19182 19183 19184It is possible to get a symbolic stack traceback 19185from anywhere in a program, just as for non-symbolic tracebacks. 19186The first step is to obtain a non-symbolic 19187traceback, and then call @code{Symbolic_Traceback} to compute the symbolic 19188information. Here is an example: 19189 19190@quotation 19191 19192@example 19193with Ada.Text_IO; 19194with GNAT.Traceback; 19195with GNAT.Traceback.Symbolic; 19196 19197procedure STB is 19198 19199 use Ada; 19200 use GNAT.Traceback; 19201 use GNAT.Traceback.Symbolic; 19202 19203 procedure P1 is 19204 TB : Tracebacks_Array (1 .. 10); 19205 -- We are asking for a maximum of 10 stack frames. 19206 Len : Natural; 19207 -- Len will receive the actual number of stack frames returned. 19208 begin 19209 Call_Chain (TB, Len); 19210 Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); 19211 end P1; 19212 19213 procedure P2 is 19214 begin 19215 P1; 19216 end P2; 19217 19218begin 19219 P2; 19220end STB; 19221@end example 19222@end quotation 19223 19224@subsubheading Automatic Symbolic Tracebacks 19225 19226 19227Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as 19228in @code{gprbuild -g ... -bargs -Es}). 19229This will cause the Exception_Information to contain a symbolic traceback, 19230which will also be printed if an unhandled exception terminates the 19231program. 19232 19233@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs 19234@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{16e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{16f} 19235@subsection Pretty-Printers for the GNAT runtime 19236 19237 19238As discussed in @cite{Calling User-Defined Subprograms}, GDB's 19239@code{print} command only knows about the physical layout of program data 19240structures and therefore normally displays only low-level dumps, which 19241are often hard to understand. 19242 19243An example of this is when trying to display the contents of an Ada 19244standard container, such as @code{Ada.Containers.Ordered_Maps.Map}: 19245 19246@quotation 19247 19248@example 19249with Ada.Containers.Ordered_Maps; 19250 19251procedure PP is 19252 package Int_To_Nat is 19253 new Ada.Containers.Ordered_Maps (Integer, Natural); 19254 19255 Map : Int_To_Nat.Map; 19256begin 19257 Map.Insert (1, 10); 19258 Map.Insert (2, 20); 19259 Map.Insert (3, 30); 19260 19261 Map.Clear; -- BREAK HERE 19262end PP; 19263@end example 19264@end quotation 19265 19266When this program is built with debugging information and run under 19267GDB up to the @code{Map.Clear} statement, trying to print @code{Map} will 19268yield information that is only relevant to the developers of our standard 19269containers: 19270 19271@quotation 19272 19273@example 19274(gdb) print map 19275$1 = ( 19276 tree => ( 19277 first => 0x64e010, 19278 last => 0x64e070, 19279 root => 0x64e040, 19280 length => 3, 19281 tc => ( 19282 busy => 0, 19283 lock => 0 19284 ) 19285 ) 19286) 19287@end example 19288@end quotation 19289 19290Fortunately, GDB has a feature called pretty-printers@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Introduction}, 19291which allows customizing how GDB displays data structures. The GDB 19292shipped with GNAT embeds such pretty-printers for the most common 19293containers in the standard library. To enable them, either run the 19294following command manually under GDB or add it to your @code{.gdbinit} file: 19295 19296@quotation 19297 19298@example 19299python import gnatdbg; gnatdbg.setup() 19300@end example 19301@end quotation 19302 19303Once this is done, GDB's @code{print} command will automatically use 19304these pretty-printers when appropriate. Using the previous example: 19305 19306@quotation 19307 19308@example 19309(gdb) print map 19310$1 = pp.int_to_nat.map of length 3 = @{ 19311 [1] = 10, 19312 [2] = 20, 19313 [3] = 30 19314@} 19315@end example 19316@end quotation 19317 19318Pretty-printers are invoked each time GDB tries to display a value, 19319including when displaying the arguments of a called subprogram (in 19320GDB's @code{backtrace} command) or when printing the value returned by a 19321function (in GDB's @code{finish} command). 19322 19323To display a value without involving pretty-printers, @code{print} can be 19324invoked with its @code{/r} option: 19325 19326@quotation 19327 19328@example 19329(gdb) print/r map 19330$1 = ( 19331 tree => (... 19332@end example 19333@end quotation 19334 19335Finer control of pretty-printers is also possible: see GDB's online documentation@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands} 19336for more information. 19337 19338@geindex Profiling 19339 19340@node Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution 19341@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{147}@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{170} 19342@section Profiling 19343 19344 19345This section describes how to use the @code{gprof} profiler tool on Ada programs. 19346 19347@geindex gprof 19348 19349@geindex Profiling 19350 19351@menu 19352* Profiling an Ada Program with gprof:: 19353 19354@end menu 19355 19356@node Profiling an Ada Program with gprof,,,Profiling 19357@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{171}@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{172} 19358@subsection Profiling an Ada Program with gprof 19359 19360 19361This section is not meant to be an exhaustive documentation of @code{gprof}. 19362Full documentation for it can be found in the @cite{GNU Profiler User's Guide} 19363documentation that is part of this GNAT distribution. 19364 19365Profiling a program helps determine the parts of a program that are executed 19366most often, and are therefore the most time-consuming. 19367 19368@code{gprof} is the standard GNU profiling tool; it has been enhanced to 19369better handle Ada programs and multitasking. 19370It is currently supported on the following platforms 19371 19372 19373@itemize * 19374 19375@item 19376linux x86/x86_64 19377 19378@item 19379windows x86 19380@end itemize 19381 19382In order to profile a program using @code{gprof}, several steps are needed: 19383 19384 19385@enumerate 19386 19387@item 19388Instrument the code, which requires a full recompilation of the project with the 19389proper switches. 19390 19391@item 19392Execute the program under the analysis conditions, i.e. with the desired 19393input. 19394 19395@item 19396Analyze the results using the @code{gprof} tool. 19397@end enumerate 19398 19399The following sections detail the different steps, and indicate how 19400to interpret the results. 19401 19402@menu 19403* Compilation for profiling:: 19404* Program execution:: 19405* Running gprof:: 19406* Interpretation of profiling results:: 19407 19408@end menu 19409 19410@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof 19411@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{173}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{174} 19412@subsubsection Compilation for profiling 19413 19414 19415@geindex -pg (gcc) 19416@geindex for profiling 19417 19418@geindex -pg (gnatlink) 19419@geindex for profiling 19420 19421In order to profile a program the first step is to tell the compiler 19422to generate the necessary profiling information. The compiler switch to be used 19423is @code{-pg}, which must be added to other compilation switches. This 19424switch needs to be specified both during compilation and link stages, and can 19425be specified once when using gnatmake: 19426 19427@quotation 19428 19429@example 19430$ gnatmake -f -pg -P my_project 19431@end example 19432@end quotation 19433 19434Note that only the objects that were compiled with the @code{-pg} switch will 19435be profiled; if you need to profile your whole project, use the @code{-f} 19436gnatmake switch to force full recompilation. 19437 19438@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof 19439@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{176} 19440@subsubsection Program execution 19441 19442 19443Once the program has been compiled for profiling, you can run it as usual. 19444 19445The only constraint imposed by profiling is that the program must terminate 19446normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be 19447properly analyzed. 19448 19449Once the program completes execution, a data file called @code{gmon.out} is 19450generated in the directory where the program was launched from. If this file 19451already exists, it will be overwritten. 19452 19453@node Running gprof,Interpretation of profiling results,Program execution,Profiling an Ada Program with gprof 19454@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{177}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{178} 19455@subsubsection Running gprof 19456 19457 19458The @code{gprof} tool is called as follow: 19459 19460@quotation 19461 19462@example 19463$ gprof my_prog gmon.out 19464@end example 19465@end quotation 19466 19467or simply: 19468 19469@quotation 19470 19471@example 19472$ gprof my_prog 19473@end example 19474@end quotation 19475 19476The complete form of the gprof command line is the following: 19477 19478@quotation 19479 19480@example 19481$ gprof [switches] [executable [data-file]] 19482@end example 19483@end quotation 19484 19485@code{gprof} supports numerous switches. The order of these 19486switch does not matter. The full list of options can be found in 19487the GNU Profiler User's Guide documentation that comes with this documentation. 19488 19489The following is the subset of those switches that is most relevant: 19490 19491@geindex --demangle (gprof) 19492 19493 19494@table @asis 19495 19496@item @code{--demangle[=@emph{style}]}, @code{--no-demangle} 19497 19498These options control whether symbol names should be demangled when 19499printing output. The default is to demangle C++ symbols. The 19500@code{--no-demangle} option may be used to turn off demangling. Different 19501compilers have different mangling styles. The optional demangling style 19502argument can be used to choose an appropriate demangling style for your 19503compiler, in particular Ada symbols generated by GNAT can be demangled using 19504@code{--demangle=gnat}. 19505@end table 19506 19507@geindex -e (gprof) 19508 19509 19510@table @asis 19511 19512@item @code{-e @emph{function_name}} 19513 19514The @code{-e @emph{function}} option tells @code{gprof} not to print 19515information about the function @code{function_name} (and its 19516children...) in the call graph. The function will still be listed 19517as a child of any functions that call it, but its index number will be 19518shown as @code{[not printed]}. More than one @code{-e} option may be 19519given; only one @code{function_name} may be indicated with each @code{-e} 19520option. 19521@end table 19522 19523@geindex -E (gprof) 19524 19525 19526@table @asis 19527 19528@item @code{-E @emph{function_name}} 19529 19530The @code{-E @emph{function}} option works like the @code{-e} option, but 19531execution time spent in the function (and children who were not called from 19532anywhere else), will not be used to compute the percentages-of-time for 19533the call graph. More than one @code{-E} option may be given; only one 19534@code{function_name} may be indicated with each @code{-E`} option. 19535@end table 19536 19537@geindex -f (gprof) 19538 19539 19540@table @asis 19541 19542@item @code{-f @emph{function_name}} 19543 19544The @code{-f @emph{function}} option causes @code{gprof} to limit the 19545call graph to the function @code{function_name} and its children (and 19546their children...). More than one @code{-f} option may be given; 19547only one @code{function_name} may be indicated with each @code{-f} 19548option. 19549@end table 19550 19551@geindex -F (gprof) 19552 19553 19554@table @asis 19555 19556@item @code{-F @emph{function_name}} 19557 19558The @code{-F @emph{function}} option works like the @code{-f} option, but 19559only time spent in the function and its children (and their 19560children...) will be used to determine total-time and 19561percentages-of-time for the call graph. More than one @code{-F} option 19562may be given; only one @code{function_name} may be indicated with each 19563@code{-F} option. The @code{-F} option overrides the @code{-E} option. 19564@end table 19565 19566@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof 19567@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{179}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{17a} 19568@subsubsection Interpretation of profiling results 19569 19570 19571The results of the profiling analysis are represented by two arrays: the 19572'flat profile' and the 'call graph'. Full documentation of those outputs 19573can be found in the GNU Profiler User's Guide. 19574 19575The flat profile shows the time spent in each function of the program, and how 19576many time it has been called. This allows you to locate easily the most 19577time-consuming functions. 19578 19579The call graph shows, for each subprogram, the subprograms that call it, 19580and the subprograms that it calls. It also provides an estimate of the time 19581spent in each of those callers/called subprograms. 19582 19583@node Improving Performance,Overflow Check Handling in GNAT,Profiling,GNAT and Program Execution 19584@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{17b}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{148} 19585@section Improving Performance 19586 19587 19588@geindex Improving performance 19589 19590This section presents several topics related to program performance. 19591It first describes some of the tradeoffs that need to be considered 19592and some of the techniques for making your program run faster. 19593 19594It then documents the unused subprogram/data elimination feature, 19595which can reduce the size of program executables. 19596 19597@menu 19598* Performance Considerations:: 19599* Text_IO Suggestions:: 19600* Reducing Size of Executables with Unused Subprogram/Data Elimination:: 19601 19602@end menu 19603 19604@node Performance Considerations,Text_IO Suggestions,,Improving Performance 19605@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17d} 19606@subsection Performance Considerations 19607 19608 19609The GNAT system provides a number of options that allow a trade-off 19610between 19611 19612 19613@itemize * 19614 19615@item 19616performance of the generated code 19617 19618@item 19619speed of compilation 19620 19621@item 19622minimization of dependences and recompilation 19623 19624@item 19625the degree of run-time checking. 19626@end itemize 19627 19628The defaults (if no options are selected) aim at improving the speed 19629of compilation and minimizing dependences, at the expense of performance 19630of the generated code: 19631 19632 19633@itemize * 19634 19635@item 19636no optimization 19637 19638@item 19639no inlining of subprogram calls 19640 19641@item 19642all run-time checks enabled except overflow and elaboration checks 19643@end itemize 19644 19645These options are suitable for most program development purposes. This 19646section describes how you can modify these choices, and also provides 19647some guidelines on debugging optimized code. 19648 19649@menu 19650* Controlling Run-Time Checks:: 19651* Use of Restrictions:: 19652* Optimization Levels:: 19653* Debugging Optimized Code:: 19654* Inlining of Subprograms:: 19655* Floating Point Operations:: 19656* Vectorization of loops:: 19657* Other Optimization Switches:: 19658* Optimization and Strict Aliasing:: 19659* Aliased Variables and Optimization:: 19660* Atomic Variables and Optimization:: 19661* Passive Task Optimization:: 19662 19663@end menu 19664 19665@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations 19666@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{17f} 19667@subsubsection Controlling Run-Time Checks 19668 19669 19670By default, GNAT generates all run-time checks, except stack overflow 19671checks, and checks for access before elaboration on subprogram 19672calls. The latter are not required in default mode, because all 19673necessary checking is done at compile time. 19674 19675@geindex -gnatp (gcc) 19676 19677@geindex -gnato (gcc) 19678 19679The gnat switch, @code{-gnatp} allows this default to be modified. See 19680@ref{ea,,Run-Time Checks}. 19681 19682Our experience is that the default is suitable for most development 19683purposes. 19684 19685Elaboration checks are off by default, and also not needed by default, since 19686GNAT uses a static elaboration analysis approach that avoids the need for 19687run-time checking. This manual contains a full chapter discussing the issue 19688of elaboration checks, and if the default is not satisfactory for your use, 19689you should read this chapter. 19690 19691For validity checks, the minimal checks required by the Ada Reference 19692Manual (for case statements and assignments to array elements) are on 19693by default. These can be suppressed by use of the @code{-gnatVn} switch. 19694Note that in Ada 83, there were no validity checks, so if the Ada 83 mode 19695is acceptable (or when comparing GNAT performance with an Ada 83 compiler), 19696it may be reasonable to routinely use @code{-gnatVn}. Validity checks 19697are also suppressed entirely if @code{-gnatp} is used. 19698 19699@geindex Overflow checks 19700 19701@geindex Checks 19702@geindex overflow 19703 19704@geindex Suppress 19705 19706@geindex Unsuppress 19707 19708@geindex pragma Suppress 19709 19710@geindex pragma Unsuppress 19711 19712Note that the setting of the switches controls the default setting of 19713the checks. They may be modified using either @code{pragma Suppress} (to 19714remove checks) or @code{pragma Unsuppress} (to add back suppressed 19715checks) in the program source. 19716 19717@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations 19718@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{181} 19719@subsubsection Use of Restrictions 19720 19721 19722The use of pragma Restrictions allows you to control which features are 19723permitted in your program. Apart from the obvious point that if you avoid 19724relatively expensive features like finalization (enforceable by the use 19725of pragma Restrictions (No_Finalization), the use of this pragma does not 19726affect the generated code in most cases. 19727 19728One notable exception to this rule is that the possibility of task abort 19729results in some distributed overhead, particularly if finalization or 19730exception handlers are used. The reason is that certain sections of code 19731have to be marked as non-abortable. 19732 19733If you use neither the @code{abort} statement, nor asynchronous transfer 19734of control (@code{select ... then abort}), then this distributed overhead 19735is removed, which may have a general positive effect in improving 19736overall performance. Especially code involving frequent use of tasking 19737constructs and controlled types will show much improved performance. 19738The relevant restrictions pragmas are 19739 19740@quotation 19741 19742@example 19743pragma Restrictions (No_Abort_Statements); 19744pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); 19745@end example 19746@end quotation 19747 19748It is recommended that these restriction pragmas be used if possible. Note 19749that this also means that you can write code without worrying about the 19750possibility of an immediate abort at any point. 19751 19752@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations 19753@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed} 19754@subsubsection Optimization Levels 19755 19756 19757@geindex -O (gcc) 19758 19759Without any optimization option, 19760the compiler's goal is to reduce the cost of 19761compilation and to make debugging produce the expected results. 19762Statements are independent: if you stop the program with a breakpoint between 19763statements, you can then assign a new value to any variable or change 19764the program counter to any other statement in the subprogram and get exactly 19765the results you would expect from the source code. 19766 19767Turning on optimization makes the compiler attempt to improve the 19768performance and/or code size at the expense of compilation time and 19769possibly the ability to debug the program. 19770 19771If you use multiple 19772-O options, with or without level numbers, 19773the last such option is the one that is effective. 19774 19775The default is optimization off. This results in the fastest compile 19776times, but GNAT makes absolutely no attempt to optimize, and the 19777generated programs are considerably larger and slower than when 19778optimization is enabled. You can use the 19779@code{-O} switch (the permitted forms are @code{-O0}, @code{-O1} 19780@code{-O2}, @code{-O3}, and @code{-Os}) 19781to @code{gcc} to control the optimization level: 19782 19783 19784@itemize * 19785 19786@item 19787 19788@table @asis 19789 19790@item @code{-O0} 19791 19792No optimization (the default); 19793generates unoptimized code but has 19794the fastest compilation time. 19795 19796Note that many other compilers do substantial optimization even 19797if 'no optimization' is specified. With gcc, it is very unusual 19798to use @code{-O0} for production if execution time is of any concern, 19799since @code{-O0} means (almost) no optimization. This difference 19800between gcc and other compilers should be kept in mind when 19801doing performance comparisons. 19802@end table 19803 19804@item 19805 19806@table @asis 19807 19808@item @code{-O1} 19809 19810Moderate optimization; 19811optimizes reasonably well but does not 19812degrade compilation time significantly. 19813@end table 19814 19815@item 19816 19817@table @asis 19818 19819@item @code{-O2} 19820 19821Full optimization; 19822generates highly optimized code and has 19823the slowest compilation time. 19824@end table 19825 19826@item 19827 19828@table @asis 19829 19830@item @code{-O3} 19831 19832Full optimization as in @code{-O2}; 19833also uses more aggressive automatic inlining of subprograms within a unit 19834(@ref{100,,Inlining of Subprograms}) and attempts to vectorize loops. 19835@end table 19836 19837@item 19838 19839@table @asis 19840 19841@item @code{-Os} 19842 19843Optimize space usage (code and data) of resulting program. 19844@end table 19845@end itemize 19846 19847Higher optimization levels perform more global transformations on the 19848program and apply more expensive analysis algorithms in order to generate 19849faster and more compact code. The price in compilation time, and the 19850resulting improvement in execution time, 19851both depend on the particular application and the hardware environment. 19852You should experiment to find the best level for your application. 19853 19854Since the precise set of optimizations done at each level will vary from 19855release to release (and sometime from target to target), it is best to think 19856of the optimization settings in general terms. 19857See the @emph{Options That Control Optimization} section in 19858@cite{Using the GNU Compiler Collection (GCC)} 19859for details about 19860the @code{-O} settings and a number of @code{-f} options that 19861individually enable or disable specific optimizations. 19862 19863Unlike some other compilation systems, @code{gcc} has 19864been tested extensively at all optimization levels. There are some bugs 19865which appear only with optimization turned on, but there have also been 19866bugs which show up only in @emph{unoptimized} code. Selecting a lower 19867level of optimization does not improve the reliability of the code 19868generator, which in practice is highly reliable at all optimization 19869levels. 19870 19871Note regarding the use of @code{-O3}: The use of this optimization level 19872ought not to be automatically preferred over that of level @code{-O2}, 19873since it often results in larger executables which may run more slowly. 19874See further discussion of this point in @ref{100,,Inlining of Subprograms}. 19875 19876@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations 19877@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{183}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{184} 19878@subsubsection Debugging Optimized Code 19879 19880 19881@geindex Debugging optimized code 19882 19883@geindex Optimization and debugging 19884 19885Although it is possible to do a reasonable amount of debugging at 19886nonzero optimization levels, 19887the higher the level the more likely that 19888source-level constructs will have been eliminated by optimization. 19889For example, if a loop is strength-reduced, the loop 19890control variable may be completely eliminated and thus cannot be 19891displayed in the debugger. 19892This can only happen at @code{-O2} or @code{-O3}. 19893Explicit temporary variables that you code might be eliminated at 19894level @code{-O1} or higher. 19895 19896@geindex -g (gcc) 19897 19898The use of the @code{-g} switch, 19899which is needed for source-level debugging, 19900affects the size of the program executable on disk, 19901and indeed the debugging information can be quite large. 19902However, it has no effect on the generated code (and thus does not 19903degrade performance) 19904 19905Since the compiler generates debugging tables for a compilation unit before 19906it performs optimizations, the optimizing transformations may invalidate some 19907of the debugging data. You therefore need to anticipate certain 19908anomalous situations that may arise while debugging optimized code. 19909These are the most common cases: 19910 19911 19912@itemize * 19913 19914@item 19915@emph{The 'hopping Program Counter':} Repeated @code{step} or @code{next} 19916commands show 19917the PC bouncing back and forth in the code. This may result from any of 19918the following optimizations: 19919 19920 19921@itemize - 19922 19923@item 19924@emph{Common subexpression elimination:} using a single instance of code for a 19925quantity that the source computes several times. As a result you 19926may not be able to stop on what looks like a statement. 19927 19928@item 19929@emph{Invariant code motion:} moving an expression that does not change within a 19930loop, to the beginning of the loop. 19931 19932@item 19933@emph{Instruction scheduling:} moving instructions so as to 19934overlap loads and stores (typically) with other code, or in 19935general to move computations of values closer to their uses. Often 19936this causes you to pass an assignment statement without the assignment 19937happening and then later bounce back to the statement when the 19938value is actually needed. Placing a breakpoint on a line of code 19939and then stepping over it may, therefore, not always cause all the 19940expected side-effects. 19941@end itemize 19942 19943@item 19944@emph{The 'big leap':} More commonly known as @emph{cross-jumping}, in which 19945two identical pieces of code are merged and the program counter suddenly 19946jumps to a statement that is not supposed to be executed, simply because 19947it (and the code following) translates to the same thing as the code 19948that @emph{was} supposed to be executed. This effect is typically seen in 19949sequences that end in a jump, such as a @code{goto}, a @code{return}, or 19950a @code{break} in a C @code{switch} statement. 19951 19952@item 19953@emph{The 'roving variable':} The symptom is an unexpected value in a variable. 19954There are various reasons for this effect: 19955 19956 19957@itemize - 19958 19959@item 19960In a subprogram prologue, a parameter may not yet have been moved to its 19961'home'. 19962 19963@item 19964A variable may be dead, and its register re-used. This is 19965probably the most common cause. 19966 19967@item 19968As mentioned above, the assignment of a value to a variable may 19969have been moved. 19970 19971@item 19972A variable may be eliminated entirely by value propagation or 19973other means. In this case, GCC may incorrectly generate debugging 19974information for the variable 19975@end itemize 19976 19977In general, when an unexpected value appears for a local variable or parameter 19978you should first ascertain if that value was actually computed by 19979your program, as opposed to being incorrectly reported by the debugger. 19980Record fields or 19981array elements in an object designated by an access value 19982are generally less of a problem, once you have ascertained that the access 19983value is sensible. 19984Typically, this means checking variables in the preceding code and in the 19985calling subprogram to verify that the value observed is explainable from other 19986values (one must apply the procedure recursively to those 19987other values); or re-running the code and stopping a little earlier 19988(perhaps before the call) and stepping to better see how the variable obtained 19989the value in question; or continuing to step @emph{from} the point of the 19990strange value to see if code motion had simply moved the variable's 19991assignments later. 19992@end itemize 19993 19994In light of such anomalies, a recommended technique is to use @code{-O0} 19995early in the software development cycle, when extensive debugging capabilities 19996are most needed, and then move to @code{-O1} and later @code{-O2} as 19997the debugger becomes less critical. 19998Whether to use the @code{-g} switch in the release version is 19999a release management issue. 20000Note that if you use @code{-g} you can then use the @code{strip} program 20001on the resulting executable, 20002which removes both debugging information and global symbols. 20003 20004@node Inlining of Subprograms,Floating Point Operations,Debugging Optimized Code,Performance Considerations 20005@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{185}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100} 20006@subsubsection Inlining of Subprograms 20007 20008 20009A call to a subprogram in the current unit is inlined if all the 20010following conditions are met: 20011 20012 20013@itemize * 20014 20015@item 20016The optimization level is at least @code{-O1}. 20017 20018@item 20019The called subprogram is suitable for inlining: It must be small enough 20020and not contain something that @code{gcc} cannot support in inlined 20021subprograms. 20022 20023@geindex pragma Inline 20024 20025@geindex Inline 20026 20027@item 20028Any one of the following applies: @code{pragma Inline} is applied to the 20029subprogram; the subprogram is local to the unit and called once from 20030within it; the subprogram is small and optimization level @code{-O2} is 20031specified; optimization level @code{-O3} is specified. 20032@end itemize 20033 20034Calls to subprograms in @emph{with}ed units are normally not inlined. 20035To achieve actual inlining (that is, replacement of the call by the code 20036in the body of the subprogram), the following conditions must all be true: 20037 20038 20039@itemize * 20040 20041@item 20042The optimization level is at least @code{-O1}. 20043 20044@item 20045The called subprogram is suitable for inlining: It must be small enough 20046and not contain something that @code{gcc} cannot support in inlined 20047subprograms. 20048 20049@item 20050There is a @code{pragma Inline} for the subprogram. 20051 20052@item 20053The @code{-gnatn} switch is used on the command line. 20054@end itemize 20055 20056Even if all these conditions are met, it may not be possible for 20057the compiler to inline the call, due to the length of the body, 20058or features in the body that make it impossible for the compiler 20059to do the inlining. 20060 20061Note that specifying the @code{-gnatn} switch causes additional 20062compilation dependencies. Consider the following: 20063 20064@quotation 20065 20066@example 20067package R is 20068 procedure Q; 20069 pragma Inline (Q); 20070end R; 20071package body R is 20072 ... 20073end R; 20074 20075with R; 20076procedure Main is 20077begin 20078 ... 20079 R.Q; 20080end Main; 20081@end example 20082@end quotation 20083 20084With the default behavior (no @code{-gnatn} switch specified), the 20085compilation of the @code{Main} procedure depends only on its own source, 20086@code{main.adb}, and the spec of the package in file @code{r.ads}. This 20087means that editing the body of @code{R} does not require recompiling 20088@code{Main}. 20089 20090On the other hand, the call @code{R.Q} is not inlined under these 20091circumstances. If the @code{-gnatn} switch is present when @code{Main} 20092is compiled, the call will be inlined if the body of @code{Q} is small 20093enough, but now @code{Main} depends on the body of @code{R} in 20094@code{r.adb} as well as on the spec. This means that if this body is edited, 20095the main program must be recompiled. Note that this extra dependency 20096occurs whether or not the call is in fact inlined by @code{gcc}. 20097 20098The use of front end inlining with @code{-gnatN} generates similar 20099additional dependencies. 20100 20101@geindex -fno-inline (gcc) 20102 20103Note: The @code{-fno-inline} switch overrides all other conditions and ensures that 20104no inlining occurs, unless requested with pragma Inline_Always for @code{gcc} 20105back-ends. The extra dependences resulting from @code{-gnatn} will still be active, 20106even if this switch is used to suppress the resulting inlining actions. 20107 20108@geindex -fno-inline-functions (gcc) 20109 20110Note: The @code{-fno-inline-functions} switch can be used to prevent 20111automatic inlining of subprograms if @code{-O3} is used. 20112 20113@geindex -fno-inline-small-functions (gcc) 20114 20115Note: The @code{-fno-inline-small-functions} switch can be used to prevent 20116automatic inlining of small subprograms if @code{-O2} is used. 20117 20118@geindex -fno-inline-functions-called-once (gcc) 20119 20120Note: The @code{-fno-inline-functions-called-once} switch 20121can be used to prevent inlining of subprograms local to the unit 20122and called once from within it if @code{-O1} is used. 20123 20124Note regarding the use of @code{-O3}: @code{-gnatn} is made up of two 20125sub-switches @code{-gnatn1} and @code{-gnatn2} that can be directly 20126specified in lieu of it, @code{-gnatn} being translated into one of them 20127based on the optimization level. With @code{-O2} or below, @code{-gnatn} 20128is equivalent to @code{-gnatn1} which activates pragma @code{Inline} with 20129moderate inlining across modules. With @code{-O3}, @code{-gnatn} is 20130equivalent to @code{-gnatn2} which activates pragma @code{Inline} with 20131full inlining across modules. If you have used pragma @code{Inline} in 20132appropriate cases, then it is usually much better to use @code{-O2} 20133and @code{-gnatn} and avoid the use of @code{-O3} which has the additional 20134effect of inlining subprograms you did not think should be inlined. We have 20135found that the use of @code{-O3} may slow down the compilation and increase 20136the code size by performing excessive inlining, leading to increased 20137instruction cache pressure from the increased code size and thus minor 20138performance improvements. So the bottom line here is that you should not 20139automatically assume that @code{-O3} is better than @code{-O2}, and 20140indeed you should use @code{-O3} only if tests show that it actually 20141improves performance for your program. 20142 20143@node Floating Point Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations 20144@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{186}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{187} 20145@subsubsection Floating Point Operations 20146 20147 20148@geindex Floating-Point Operations 20149 20150On almost all targets, GNAT maps Float and Long_Float to the 32-bit and 2015164-bit standard IEEE floating-point representations, and operations will 20152use standard IEEE arithmetic as provided by the processor. On most, but 20153not all, architectures, the attribute Machine_Overflows is False for these 20154types, meaning that the semantics of overflow is implementation-defined. 20155In the case of GNAT, these semantics correspond to the normal IEEE 20156treatment of infinities and NaN (not a number) values. For example, 201571.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By 20158avoiding explicit overflow checks, the performance is greatly improved 20159on many targets. However, if required, floating-point overflow can be 20160enabled by the use of the pragma Check_Float_Overflow. 20161 20162Another consideration that applies specifically to x86 32-bit 20163architectures is which form of floating-point arithmetic is used. 20164By default the operations use the old style x86 floating-point, 20165which implements an 80-bit extended precision form (on these 20166architectures the type Long_Long_Float corresponds to that form). 20167In addition, generation of efficient code in this mode means that 20168the extended precision form will be used for intermediate results. 20169This may be helpful in improving the final precision of a complex 20170expression. However it means that the results obtained on the x86 20171will be different from those on other architectures, and for some 20172algorithms, the extra intermediate precision can be detrimental. 20173 20174In addition to this old-style floating-point, all modern x86 chips 20175implement an alternative floating-point operation model referred 20176to as SSE2. In this model there is no extended form, and furthermore 20177execution performance is significantly enhanced. To force GNAT to use 20178this more modern form, use both of the switches: 20179 20180@quotation 20181 20182-msse2 -mfpmath=sse 20183@end quotation 20184 20185A unit compiled with these switches will automatically use the more 20186efficient SSE2 instruction set for Float and Long_Float operations. 20187Note that the ABI has the same form for both floating-point models, 20188so it is permissible to mix units compiled with and without these 20189switches. 20190 20191@node Vectorization of loops,Other Optimization Switches,Floating Point Operations,Performance Considerations 20192@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{189} 20193@subsubsection Vectorization of loops 20194 20195 20196@geindex Optimization Switches 20197 20198You can take advantage of the auto-vectorizer present in the @code{gcc} 20199back end to vectorize loops with GNAT. The corresponding command line switch 20200is @code{-ftree-vectorize} but, as it is enabled by default at @code{-O3} 20201and other aggressive optimizations helpful for vectorization also are enabled 20202by default at this level, using @code{-O3} directly is recommended. 20203 20204You also need to make sure that the target architecture features a supported 20205SIMD instruction set. For example, for the x86 architecture, you should at 20206least specify @code{-msse2} to get significant vectorization (but you don't 20207need to specify it for x86-64 as it is part of the base 64-bit architecture). 20208Similarly, for the PowerPC architecture, you should specify @code{-maltivec}. 20209 20210The preferred loop form for vectorization is the @code{for} iteration scheme. 20211Loops with a @code{while} iteration scheme can also be vectorized if they are 20212very simple, but the vectorizer will quickly give up otherwise. With either 20213iteration scheme, the flow of control must be straight, in particular no 20214@code{exit} statement may appear in the loop body. The loop may however 20215contain a single nested loop, if it can be vectorized when considered alone: 20216 20217@quotation 20218 20219@example 20220A : array (1..4, 1..4) of Long_Float; 20221S : array (1..4) of Long_Float; 20222 20223procedure Sum is 20224begin 20225 for I in A'Range(1) loop 20226 for J in A'Range(2) loop 20227 S (I) := S (I) + A (I, J); 20228 end loop; 20229 end loop; 20230end Sum; 20231@end example 20232@end quotation 20233 20234The vectorizable operations depend on the targeted SIMD instruction set, but 20235the adding and some of the multiplying operators are generally supported, as 20236well as the logical operators for modular types. Note that compiling 20237with @code{-gnatp} might well reveal cases where some checks do thwart 20238vectorization. 20239 20240Type conversions may also prevent vectorization if they involve semantics that 20241are not directly supported by the code generator or the SIMD instruction set. 20242A typical example is direct conversion from floating-point to integer types. 20243The solution in this case is to use the following idiom: 20244 20245@quotation 20246 20247@example 20248Integer (S'Truncation (F)) 20249@end example 20250@end quotation 20251 20252if @code{S} is the subtype of floating-point object @code{F}. 20253 20254In most cases, the vectorizable loops are loops that iterate over arrays. 20255All kinds of array types are supported, i.e. constrained array types with 20256static bounds: 20257 20258@quotation 20259 20260@example 20261type Array_Type is array (1 .. 4) of Long_Float; 20262@end example 20263@end quotation 20264 20265constrained array types with dynamic bounds: 20266 20267@quotation 20268 20269@example 20270type Array_Type is array (1 .. Q.N) of Long_Float; 20271 20272type Array_Type is array (Q.K .. 4) of Long_Float; 20273 20274type Array_Type is array (Q.K .. Q.N) of Long_Float; 20275@end example 20276@end quotation 20277 20278or unconstrained array types: 20279 20280@quotation 20281 20282@example 20283type Array_Type is array (Positive range <>) of Long_Float; 20284@end example 20285@end quotation 20286 20287The quality of the generated code decreases when the dynamic aspect of the 20288array type increases, the worst code being generated for unconstrained array 20289types. This is so because, the less information the compiler has about the 20290bounds of the array, the more fallback code it needs to generate in order to 20291fix things up at run time. 20292 20293It is possible to specify that a given loop should be subject to vectorization 20294preferably to other optimizations by means of pragma @code{Loop_Optimize}: 20295 20296@quotation 20297 20298@example 20299pragma Loop_Optimize (Vector); 20300@end example 20301@end quotation 20302 20303placed immediately within the loop will convey the appropriate hint to the 20304compiler for this loop. 20305 20306It is also possible to help the compiler generate better vectorized code 20307for a given loop by asserting that there are no loop-carried dependencies 20308in the loop. Consider for example the procedure: 20309 20310@quotation 20311 20312@example 20313type Arr is array (1 .. 4) of Long_Float; 20314 20315procedure Add (X, Y : not null access Arr; R : not null access Arr) is 20316begin 20317 for I in Arr'Range loop 20318 R(I) := X(I) + Y(I); 20319 end loop; 20320end; 20321@end example 20322@end quotation 20323 20324By default, the compiler cannot unconditionally vectorize the loop because 20325assigning to a component of the array designated by R in one iteration could 20326change the value read from the components of the array designated by X or Y 20327in a later iteration. As a result, the compiler will generate two versions 20328of the loop in the object code, one vectorized and the other not vectorized, 20329as well as a test to select the appropriate version at run time. This can 20330be overcome by another hint: 20331 20332@quotation 20333 20334@example 20335pragma Loop_Optimize (Ivdep); 20336@end example 20337@end quotation 20338 20339placed immediately within the loop will tell the compiler that it can safely 20340omit the non-vectorized version of the loop as well as the run-time test. 20341 20342@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations 20343@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{18b} 20344@subsubsection Other Optimization Switches 20345 20346 20347@geindex Optimization Switches 20348 20349Since GNAT uses the @code{gcc} back end, all the specialized 20350@code{gcc} optimization switches are potentially usable. These switches 20351have not been extensively tested with GNAT but can generally be expected 20352to work. Examples of switches in this category are @code{-funroll-loops} 20353and the various target-specific @code{-m} options (in particular, it has 20354been observed that @code{-march=xxx} can significantly improve performance 20355on appropriate machines). For full details of these switches, see 20356the @emph{Submodel Options} section in the @emph{Hardware Models and Configurations} 20357chapter of @cite{Using the GNU Compiler Collection (GCC)}. 20358 20359@node Optimization and Strict Aliasing,Aliased Variables and Optimization,Other Optimization Switches,Performance Considerations 20360@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4}@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{18c} 20361@subsubsection Optimization and Strict Aliasing 20362 20363 20364@geindex Aliasing 20365 20366@geindex Strict Aliasing 20367 20368@geindex No_Strict_Aliasing 20369 20370The strong typing capabilities of Ada allow an optimizer to generate 20371efficient code in situations where other languages would be forced to 20372make worst case assumptions preventing such optimizations. Consider 20373the following example: 20374 20375@quotation 20376 20377@example 20378procedure R is 20379 type Int1 is new Integer; 20380 type Int2 is new Integer; 20381 type Int1A is access Int1; 20382 type Int2A is access Int2; 20383 Int1V : Int1A; 20384 Int2V : Int2A; 20385 ... 20386 20387begin 20388 ... 20389 for J in Data'Range loop 20390 if Data (J) = Int1V.all then 20391 Int2V.all := Int2V.all + 1; 20392 end if; 20393 end loop; 20394 ... 20395end R; 20396@end example 20397@end quotation 20398 20399In this example, since the variable @code{Int1V} can only access objects 20400of type @code{Int1}, and @code{Int2V} can only access objects of type 20401@code{Int2}, there is no possibility that the assignment to 20402@code{Int2V.all} affects the value of @code{Int1V.all}. This means that 20403the compiler optimizer can "know" that the value @code{Int1V.all} is constant 20404for all iterations of the loop and avoid the extra memory reference 20405required to dereference it each time through the loop. 20406 20407This kind of optimization, called strict aliasing analysis, is 20408triggered by specifying an optimization level of @code{-O2} or 20409higher or @code{-Os} and allows GNAT to generate more efficient code 20410when access values are involved. 20411 20412However, although this optimization is always correct in terms of 20413the formal semantics of the Ada Reference Manual, difficulties can 20414arise if features like @code{Unchecked_Conversion} are used to break 20415the typing system. Consider the following complete program example: 20416 20417@quotation 20418 20419@example 20420package p1 is 20421 type int1 is new integer; 20422 type int2 is new integer; 20423 type a1 is access int1; 20424 type a2 is access int2; 20425end p1; 20426 20427with p1; use p1; 20428package p2 is 20429 function to_a2 (Input : a1) return a2; 20430end p2; 20431 20432with Unchecked_Conversion; 20433package body p2 is 20434 function to_a2 (Input : a1) return a2 is 20435 function to_a2u is 20436 new Unchecked_Conversion (a1, a2); 20437 begin 20438 return to_a2u (Input); 20439 end to_a2; 20440end p2; 20441 20442with p2; use p2; 20443with p1; use p1; 20444with Text_IO; use Text_IO; 20445procedure m is 20446 v1 : a1 := new int1; 20447 v2 : a2 := to_a2 (v1); 20448begin 20449 v1.all := 1; 20450 v2.all := 0; 20451 put_line (int1'image (v1.all)); 20452end; 20453@end example 20454@end quotation 20455 20456This program prints out 0 in @code{-O0} or @code{-O1} 20457mode, but it prints out 1 in @code{-O2} mode. That's 20458because in strict aliasing mode, the compiler can and 20459does assume that the assignment to @code{v2.all} could not 20460affect the value of @code{v1.all}, since different types 20461are involved. 20462 20463This behavior is not a case of non-conformance with the standard, since 20464the Ada RM specifies that an unchecked conversion where the resulting 20465bit pattern is not a correct value of the target type can result in an 20466abnormal value and attempting to reference an abnormal value makes the 20467execution of a program erroneous. That's the case here since the result 20468does not point to an object of type @code{int2}. This means that the 20469effect is entirely unpredictable. 20470 20471However, although that explanation may satisfy a language 20472lawyer, in practice an applications programmer expects an 20473unchecked conversion involving pointers to create true 20474aliases and the behavior of printing 1 seems plain wrong. 20475In this case, the strict aliasing optimization is unwelcome. 20476 20477Indeed the compiler recognizes this possibility, and the 20478unchecked conversion generates a warning: 20479 20480@quotation 20481 20482@example 20483p2.adb:5:07: warning: possible aliasing problem with type "a2" 20484p2.adb:5:07: warning: use -fno-strict-aliasing switch for references 20485p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" 20486@end example 20487@end quotation 20488 20489Unfortunately the problem is recognized when compiling the body of 20490package @code{p2}, but the actual "bad" code is generated while 20491compiling the body of @code{m} and this latter compilation does not see 20492the suspicious @code{Unchecked_Conversion}. 20493 20494As implied by the warning message, there are approaches you can use to 20495avoid the unwanted strict aliasing optimization in a case like this. 20496 20497One possibility is to simply avoid the use of @code{-O2}, but 20498that is a bit drastic, since it throws away a number of useful 20499optimizations that do not involve strict aliasing assumptions. 20500 20501A less drastic approach is to compile the program using the 20502option @code{-fno-strict-aliasing}. Actually it is only the 20503unit containing the dereferencing of the suspicious pointer 20504that needs to be compiled. So in this case, if we compile 20505unit @code{m} with this switch, then we get the expected 20506value of zero printed. Analyzing which units might need 20507the switch can be painful, so a more reasonable approach 20508is to compile the entire program with options @code{-O2} 20509and @code{-fno-strict-aliasing}. If the performance is 20510satisfactory with this combination of options, then the 20511advantage is that the entire issue of possible "wrong" 20512optimization due to strict aliasing is avoided. 20513 20514To avoid the use of compiler switches, the configuration 20515pragma @code{No_Strict_Aliasing} with no parameters may be 20516used to specify that for all access types, the strict 20517aliasing optimization should be suppressed. 20518 20519However, these approaches are still overkill, in that they causes 20520all manipulations of all access values to be deoptimized. A more 20521refined approach is to concentrate attention on the specific 20522access type identified as problematic. 20523 20524First, if a careful analysis of uses of the pointer shows 20525that there are no possible problematic references, then 20526the warning can be suppressed by bracketing the 20527instantiation of @code{Unchecked_Conversion} to turn 20528the warning off: 20529 20530@quotation 20531 20532@example 20533pragma Warnings (Off); 20534function to_a2u is 20535 new Unchecked_Conversion (a1, a2); 20536pragma Warnings (On); 20537@end example 20538@end quotation 20539 20540Of course that approach is not appropriate for this particular 20541example, since indeed there is a problematic reference. In this 20542case we can take one of two other approaches. 20543 20544The first possibility is to move the instantiation of unchecked 20545conversion to the unit in which the type is declared. In 20546this example, we would move the instantiation of 20547@code{Unchecked_Conversion} from the body of package 20548@code{p2} to the spec of package @code{p1}. Now the 20549warning disappears. That's because any use of the 20550access type knows there is a suspicious unchecked 20551conversion, and the strict aliasing optimization 20552is automatically suppressed for the type. 20553 20554If it is not practical to move the unchecked conversion to the same unit 20555in which the destination access type is declared (perhaps because the 20556source type is not visible in that unit), you may use pragma 20557@code{No_Strict_Aliasing} for the type. This pragma must occur in the 20558same declarative sequence as the declaration of the access type: 20559 20560@quotation 20561 20562@example 20563type a2 is access int2; 20564pragma No_Strict_Aliasing (a2); 20565@end example 20566@end quotation 20567 20568Here again, the compiler now knows that the strict aliasing optimization 20569should be suppressed for any reference to type @code{a2} and the 20570expected behavior is obtained. 20571 20572Finally, note that although the compiler can generate warnings for 20573simple cases of unchecked conversions, there are tricker and more 20574indirect ways of creating type incorrect aliases which the compiler 20575cannot detect. Examples are the use of address overlays and unchecked 20576conversions involving composite types containing access types as 20577components. In such cases, no warnings are generated, but there can 20578still be aliasing problems. One safe coding practice is to forbid the 20579use of address clauses for type overlaying, and to allow unchecked 20580conversion only for primitive types. This is not really a significant 20581restriction since any possible desired effect can be achieved by 20582unchecked conversion of access values. 20583 20584The aliasing analysis done in strict aliasing mode can certainly 20585have significant benefits. We have seen cases of large scale 20586application code where the time is increased by up to 5% by turning 20587this optimization off. If you have code that includes significant 20588usage of unchecked conversion, you might want to just stick with 20589@code{-O1} and avoid the entire issue. If you get adequate 20590performance at this level of optimization level, that's probably 20591the safest approach. If tests show that you really need higher 20592levels of optimization, then you can experiment with @code{-O2} 20593and @code{-O2 -fno-strict-aliasing} to see how much effect this 20594has on size and speed of the code. If you really need to use 20595@code{-O2} with strict aliasing in effect, then you should 20596review any uses of unchecked conversion of access types, 20597particularly if you are getting the warnings described above. 20598 20599@node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations 20600@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{18d}@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{18e} 20601@subsubsection Aliased Variables and Optimization 20602 20603 20604@geindex Aliasing 20605 20606There are scenarios in which programs may 20607use low level techniques to modify variables 20608that otherwise might be considered to be unassigned. For example, 20609a variable can be passed to a procedure by reference, which takes 20610the address of the parameter and uses the address to modify the 20611variable's value, even though it is passed as an IN parameter. 20612Consider the following example: 20613 20614@quotation 20615 20616@example 20617procedure P is 20618 Max_Length : constant Natural := 16; 20619 type Char_Ptr is access all Character; 20620 20621 procedure Get_String(Buffer: Char_Ptr; Size : Integer); 20622 pragma Import (C, Get_String, "get_string"); 20623 20624 Name : aliased String (1 .. Max_Length) := (others => ' '); 20625 Temp : Char_Ptr; 20626 20627 function Addr (S : String) return Char_Ptr is 20628 function To_Char_Ptr is 20629 new Ada.Unchecked_Conversion (System.Address, Char_Ptr); 20630 begin 20631 return To_Char_Ptr (S (S'First)'Address); 20632 end; 20633 20634begin 20635 Temp := Addr (Name); 20636 Get_String (Temp, Max_Length); 20637end; 20638@end example 20639@end quotation 20640 20641where Get_String is a C function that uses the address in Temp to 20642modify the variable @code{Name}. This code is dubious, and arguably 20643erroneous, and the compiler would be entitled to assume that 20644@code{Name} is never modified, and generate code accordingly. 20645 20646However, in practice, this would cause some existing code that 20647seems to work with no optimization to start failing at high 20648levels of optimzization. 20649 20650What the compiler does for such cases is to assume that marking 20651a variable as aliased indicates that some "funny business" may 20652be going on. The optimizer recognizes the aliased keyword and 20653inhibits optimizations that assume the value cannot be assigned. 20654This means that the above example will in fact "work" reliably, 20655that is, it will produce the expected results. 20656 20657@node Atomic Variables and Optimization,Passive Task Optimization,Aliased Variables and Optimization,Performance Considerations 20658@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190} 20659@subsubsection Atomic Variables and Optimization 20660 20661 20662@geindex Atomic 20663 20664There are two considerations with regard to performance when 20665atomic variables are used. 20666 20667First, the RM only guarantees that access to atomic variables 20668be atomic, it has nothing to say about how this is achieved, 20669though there is a strong implication that this should not be 20670achieved by explicit locking code. Indeed GNAT will never 20671generate any locking code for atomic variable access (it will 20672simply reject any attempt to make a variable or type atomic 20673if the atomic access cannot be achieved without such locking code). 20674 20675That being said, it is important to understand that you cannot 20676assume that the entire variable will always be accessed. Consider 20677this example: 20678 20679@quotation 20680 20681@example 20682type R is record 20683 A,B,C,D : Character; 20684end record; 20685for R'Size use 32; 20686for R'Alignment use 4; 20687 20688RV : R; 20689pragma Atomic (RV); 20690X : Character; 20691... 20692X := RV.B; 20693@end example 20694@end quotation 20695 20696You cannot assume that the reference to @code{RV.B} 20697will read the entire 32-bit 20698variable with a single load instruction. It is perfectly legitimate if 20699the hardware allows it to do a byte read of just the B field. This read 20700is still atomic, which is all the RM requires. GNAT can and does take 20701advantage of this, depending on the architecture and optimization level. 20702Any assumption to the contrary is non-portable and risky. Even if you 20703examine the assembly language and see a full 32-bit load, this might 20704change in a future version of the compiler. 20705 20706If your application requires that all accesses to @code{RV} in this 20707example be full 32-bit loads, you need to make a copy for the access 20708as in: 20709 20710@quotation 20711 20712@example 20713declare 20714 RV_Copy : constant R := RV; 20715begin 20716 X := RV_Copy.B; 20717end; 20718@end example 20719@end quotation 20720 20721Now the reference to RV must read the whole variable. 20722Actually one can imagine some compiler which figures 20723out that the whole copy is not required (because only 20724the B field is actually accessed), but GNAT 20725certainly won't do that, and we don't know of any 20726compiler that would not handle this right, and the 20727above code will in practice work portably across 20728all architectures (that permit the Atomic declaration). 20729 20730The second issue with atomic variables has to do with 20731the possible requirement of generating synchronization 20732code. For more details on this, consult the sections on 20733the pragmas Enable/Disable_Atomic_Synchronization in the 20734GNAT Reference Manual. If performance is critical, and 20735such synchronization code is not required, it may be 20736useful to disable it. 20737 20738@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations 20739@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{192} 20740@subsubsection Passive Task Optimization 20741 20742 20743@geindex Passive Task 20744 20745A passive task is one which is sufficiently simple that 20746in theory a compiler could recognize it an implement it 20747efficiently without creating a new thread. The original design 20748of Ada 83 had in mind this kind of passive task optimization, but 20749only a few Ada 83 compilers attempted it. The problem was that 20750it was difficult to determine the exact conditions under which 20751the optimization was possible. The result is a very fragile 20752optimization where a very minor change in the program can 20753suddenly silently make a task non-optimizable. 20754 20755With the revisiting of this issue in Ada 95, there was general 20756agreement that this approach was fundamentally flawed, and the 20757notion of protected types was introduced. When using protected 20758types, the restrictions are well defined, and you KNOW that the 20759operations will be optimized, and furthermore this optimized 20760performance is fully portable. 20761 20762Although it would theoretically be possible for GNAT to attempt to 20763do this optimization, but it really doesn't make sense in the 20764context of Ada 95, and none of the Ada 95 compilers implement 20765this optimization as far as we know. In particular GNAT never 20766attempts to perform this optimization. 20767 20768In any new Ada 95 code that is written, you should always 20769use protected types in place of tasks that might be able to 20770be optimized in this manner. 20771Of course this does not help if you have legacy Ada 83 code 20772that depends on this optimization, but it is unusual to encounter 20773a case where the performance gains from this optimization 20774are significant. 20775 20776Your program should work correctly without this optimization. If 20777you have performance problems, then the most practical 20778approach is to figure out exactly where these performance problems 20779arise, and update those particular tasks to be protected types. Note 20780that typically clients of the tasks who call entries, will not have 20781to be modified, only the task definition itself. 20782 20783@node Text_IO Suggestions,Reducing Size of Executables with Unused Subprogram/Data Elimination,Performance Considerations,Improving Performance 20784@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{193}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{194} 20785@subsection @code{Text_IO} Suggestions 20786 20787 20788@geindex Text_IO and performance 20789 20790The @code{Ada.Text_IO} package has fairly high overheads due in part to 20791the requirement of maintaining page and line counts. If performance 20792is critical, a recommendation is to use @code{Stream_IO} instead of 20793@code{Text_IO} for volume output, since this package has less overhead. 20794 20795If @code{Text_IO} must be used, note that by default output to the standard 20796output and standard error files is unbuffered (this provides better 20797behavior when output statements are used for debugging, or if the 20798progress of a program is observed by tracking the output, e.g. by 20799using the Unix @emph{tail -f} command to watch redirected output. 20800 20801If you are generating large volumes of output with @code{Text_IO} and 20802performance is an important factor, use a designated file instead 20803of the standard output file, or change the standard output file to 20804be buffered using @code{Interfaces.C_Streams.setvbuf}. 20805 20806@node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance 20807@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{195}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{196} 20808@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination 20809 20810 20811@geindex Uunused subprogram/data elimination 20812 20813This section describes how you can eliminate unused subprograms and data from 20814your executable just by setting options at compilation time. 20815 20816@menu 20817* About unused subprogram/data elimination:: 20818* Compilation options:: 20819* Example of unused subprogram/data elimination:: 20820 20821@end menu 20822 20823@node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination 20824@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{197}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{198} 20825@subsubsection About unused subprogram/data elimination 20826 20827 20828By default, an executable contains all code and data of its composing objects 20829(directly linked or coming from statically linked libraries), even data or code 20830never used by this executable. 20831 20832This feature will allow you to eliminate such unused code from your 20833executable, making it smaller (in disk and in memory). 20834 20835This functionality is available on all Linux platforms except for the IA-64 20836architecture and on all cross platforms using the ELF binary file format. 20837In both cases GNU binutils version 2.16 or later are required to enable it. 20838 20839@node Compilation options,Example of unused subprogram/data elimination,About unused subprogram/data elimination,Reducing Size of Executables with Unused Subprogram/Data Elimination 20840@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{19a} 20841@subsubsection Compilation options 20842 20843 20844The operation of eliminating the unused code and data from the final executable 20845is directly performed by the linker. 20846 20847@geindex -ffunction-sections (gcc) 20848 20849@geindex -fdata-sections (gcc) 20850 20851In order to do this, it has to work with objects compiled with the 20852following options: 20853@code{-ffunction-sections} @code{-fdata-sections}. 20854 20855These options are usable with C and Ada files. 20856They will place respectively each 20857function or data in a separate section in the resulting object file. 20858 20859Once the objects and static libraries are created with these options, the 20860linker can perform the dead code elimination. You can do this by setting 20861the @code{-Wl,--gc-sections} option to gcc command or in the 20862@code{-largs} section of @code{gnatmake}. This will perform a 20863garbage collection of code and data never referenced. 20864 20865If the linker performs a partial link (@code{-r} linker option), then you 20866will need to provide the entry point using the @code{-e} / @code{--entry} 20867linker option. 20868 20869Note that objects compiled without the @code{-ffunction-sections} and 20870@code{-fdata-sections} options can still be linked with the executable. 20871However, no dead code elimination will be performed on those objects (they will 20872be linked as is). 20873 20874The GNAT static library is now compiled with -ffunction-sections and 20875-fdata-sections on some platforms. This allows you to eliminate the unused code 20876and data of the GNAT library from your executable. 20877 20878@node Example of unused subprogram/data elimination,,Compilation options,Reducing Size of Executables with Unused Subprogram/Data Elimination 20879@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{19b}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{19c} 20880@subsubsection Example of unused subprogram/data elimination 20881 20882 20883Here is a simple example: 20884 20885@quotation 20886 20887@example 20888with Aux; 20889 20890procedure Test is 20891begin 20892 Aux.Used (10); 20893end Test; 20894 20895package Aux is 20896 Used_Data : Integer; 20897 Unused_Data : Integer; 20898 20899 procedure Used (Data : Integer); 20900 procedure Unused (Data : Integer); 20901end Aux; 20902 20903package body Aux is 20904 procedure Used (Data : Integer) is 20905 begin 20906 Used_Data := Data; 20907 end Used; 20908 20909 procedure Unused (Data : Integer) is 20910 begin 20911 Unused_Data := Data; 20912 end Unused; 20913end Aux; 20914@end example 20915@end quotation 20916 20917@code{Unused} and @code{Unused_Data} are never referenced in this code 20918excerpt, and hence they may be safely removed from the final executable. 20919 20920@quotation 20921 20922@example 20923$ gnatmake test 20924 20925$ nm test | grep used 20926020015f0 T aux__unused 2092702005d88 B aux__unused_data 20928020015cc T aux__used 2092902005d84 B aux__used_data 20930 20931$ gnatmake test -cargs -fdata-sections -ffunction-sections \\ 20932 -largs -Wl,--gc-sections 20933 20934$ nm test | grep used 2093502005350 T aux__used 209360201ffe0 B aux__used_data 20937@end example 20938@end quotation 20939 20940It can be observed that the procedure @code{Unused} and the object 20941@code{Unused_Data} are removed by the linker when using the 20942appropriate options. 20943 20944@geindex Overflow checks 20945 20946@geindex Checks (overflow) 20947 20948@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution 20949@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{149}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{19d} 20950@section Overflow Check Handling in GNAT 20951 20952 20953This section explains how to control the handling of overflow checks. 20954 20955@menu 20956* Background:: 20957* Management of Overflows in GNAT:: 20958* Specifying the Desired Mode:: 20959* Default Settings:: 20960* Implementation Notes:: 20961 20962@end menu 20963 20964@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT 20965@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19f} 20966@subsection Background 20967 20968 20969Overflow checks are checks that the compiler may make to ensure 20970that intermediate results are not out of range. For example: 20971 20972@quotation 20973 20974@example 20975A : Integer; 20976... 20977A := A + 1; 20978@end example 20979@end quotation 20980 20981If @code{A} has the value @code{Integer'Last}, then the addition may cause 20982overflow since the result is out of range of the type @code{Integer}. 20983In this case @code{Constraint_Error} will be raised if checks are 20984enabled. 20985 20986A trickier situation arises in examples like the following: 20987 20988@quotation 20989 20990@example 20991A, C : Integer; 20992... 20993A := (A + 1) + C; 20994@end example 20995@end quotation 20996 20997where @code{A} is @code{Integer'Last} and @code{C} is @code{-1}. 20998Now the final result of the expression on the right hand side is 20999@code{Integer'Last} which is in range, but the question arises whether the 21000intermediate addition of @code{(A + 1)} raises an overflow error. 21001 21002The (perhaps surprising) answer is that the Ada language 21003definition does not answer this question. Instead it leaves 21004it up to the implementation to do one of two things if overflow 21005checks are enabled. 21006 21007 21008@itemize * 21009 21010@item 21011raise an exception (@code{Constraint_Error}), or 21012 21013@item 21014yield the correct mathematical result which is then used in 21015subsequent operations. 21016@end itemize 21017 21018If the compiler chooses the first approach, then the assignment of this 21019example will indeed raise @code{Constraint_Error} if overflow checking is 21020enabled, or result in erroneous execution if overflow checks are suppressed. 21021 21022But if the compiler 21023chooses the second approach, then it can perform both additions yielding 21024the correct mathematical result, which is in range, so no exception 21025will be raised, and the right result is obtained, regardless of whether 21026overflow checks are suppressed. 21027 21028Note that in the first example an 21029exception will be raised in either case, since if the compiler 21030gives the correct mathematical result for the addition, it will 21031be out of range of the target type of the assignment, and thus 21032fails the range check. 21033 21034This lack of specified behavior in the handling of overflow for 21035intermediate results is a source of non-portability, and can thus 21036be problematic when programs are ported. Most typically this arises 21037in a situation where the original compiler did not raise an exception, 21038and then the application is moved to a compiler where the check is 21039performed on the intermediate result and an unexpected exception is 21040raised. 21041 21042Furthermore, when using Ada 2012's preconditions and other 21043assertion forms, another issue arises. Consider: 21044 21045@quotation 21046 21047@example 21048procedure P (A, B : Integer) with 21049 Pre => A + B <= Integer'Last; 21050@end example 21051@end quotation 21052 21053One often wants to regard arithmetic in a context like this from 21054a mathematical point of view. So for example, if the two actual parameters 21055for a call to @code{P} are both @code{Integer'Last}, then 21056the precondition should be regarded as False. If we are executing 21057in a mode with run-time checks enabled for preconditions, then we would 21058like this precondition to fail, rather than raising an exception 21059because of the intermediate overflow. 21060 21061However, the language definition leaves the specification of 21062whether the above condition fails (raising @code{Assert_Error}) or 21063causes an intermediate overflow (raising @code{Constraint_Error}) 21064up to the implementation. 21065 21066The situation is worse in a case such as the following: 21067 21068@quotation 21069 21070@example 21071procedure Q (A, B, C : Integer) with 21072 Pre => A + B + C <= Integer'Last; 21073@end example 21074@end quotation 21075 21076Consider the call 21077 21078@quotation 21079 21080@example 21081Q (A => Integer'Last, B => 1, C => -1); 21082@end example 21083@end quotation 21084 21085From a mathematical point of view the precondition 21086is True, but at run time we may (but are not guaranteed to) get an 21087exception raised because of the intermediate overflow (and we really 21088would prefer this precondition to be considered True at run time). 21089 21090@node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT 21091@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1a1} 21092@subsection Management of Overflows in GNAT 21093 21094 21095To deal with the portability issue, and with the problem of 21096mathematical versus run-time interpretation of the expressions in 21097assertions, GNAT provides comprehensive control over the handling 21098of intermediate overflow. GNAT can operate in three modes, and 21099furthemore, permits separate selection of operating modes for 21100the expressions within assertions (here the term 'assertions' 21101is used in the technical sense, which includes preconditions and so forth) 21102and for expressions appearing outside assertions. 21103 21104The three modes are: 21105 21106 21107@itemize * 21108 21109@item 21110@emph{Use base type for intermediate operations} (@code{STRICT}) 21111 21112In this mode, all intermediate results for predefined arithmetic 21113operators are computed using the base type, and the result must 21114be in range of the base type. If this is not the 21115case then either an exception is raised (if overflow checks are 21116enabled) or the execution is erroneous (if overflow checks are suppressed). 21117This is the normal default mode. 21118 21119@item 21120@emph{Most intermediate overflows avoided} (@code{MINIMIZED}) 21121 21122In this mode, the compiler attempts to avoid intermediate overflows by 21123using a larger integer type, typically @code{Long_Long_Integer}, 21124as the type in which arithmetic is 21125performed for predefined arithmetic operators. This may be slightly more 21126expensive at 21127run time (compared to suppressing intermediate overflow checks), though 21128the cost is negligible on modern 64-bit machines. For the examples given 21129earlier, no intermediate overflows would have resulted in exceptions, 21130since the intermediate results are all in the range of 21131@code{Long_Long_Integer} (typically 64-bits on nearly all implementations 21132of GNAT). In addition, if checks are enabled, this reduces the number of 21133checks that must be made, so this choice may actually result in an 21134improvement in space and time behavior. 21135 21136However, there are cases where @code{Long_Long_Integer} is not large 21137enough, consider the following example: 21138 21139@quotation 21140 21141@example 21142procedure R (A, B, C, D : Integer) with 21143 Pre => (A**2 * B**2) / (C**2 * D**2) <= 10; 21144@end example 21145@end quotation 21146 21147where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}. 21148Now the intermediate results are 21149out of the range of @code{Long_Long_Integer} even though the final result 21150is in range and the precondition is True (from a mathematical point 21151of view). In such a case, operating in this mode, an overflow occurs 21152for the intermediate computation (which is why this mode 21153says @emph{most} intermediate overflows are avoided). In this case, 21154an exception is raised if overflow checks are enabled, and the 21155execution is erroneous if overflow checks are suppressed. 21156 21157@item 21158@emph{All intermediate overflows avoided} (@code{ELIMINATED}) 21159 21160In this mode, the compiler avoids all intermediate overflows 21161by using arbitrary precision arithmetic as required. In this 21162mode, the above example with @code{A**2 * B**2} would 21163not cause intermediate overflow, because the intermediate result 21164would be evaluated using sufficient precision, and the result 21165of evaluating the precondition would be True. 21166 21167This mode has the advantage of avoiding any intermediate 21168overflows, but at the expense of significant run-time overhead, 21169including the use of a library (included automatically in this 21170mode) for multiple-precision arithmetic. 21171 21172This mode provides cleaner semantics for assertions, since now 21173the run-time behavior emulates true arithmetic behavior for the 21174predefined arithmetic operators, meaning that there is never a 21175conflict between the mathematical view of the assertion, and its 21176run-time behavior. 21177 21178Note that in this mode, the behavior is unaffected by whether or 21179not overflow checks are suppressed, since overflow does not occur. 21180It is possible for gigantic intermediate expressions to raise 21181@code{Storage_Error} as a result of attempting to compute the 21182results of such expressions (e.g. @code{Integer'Last ** Integer'Last}) 21183but overflow is impossible. 21184@end itemize 21185 21186Note that these modes apply only to the evaluation of predefined 21187arithmetic, membership, and comparison operators for signed integer 21188arithmetic. 21189 21190For fixed-point arithmetic, checks can be suppressed. But if checks 21191are enabled 21192then fixed-point values are always checked for overflow against the 21193base type for intermediate expressions (that is such checks always 21194operate in the equivalent of @code{STRICT} mode). 21195 21196For floating-point, on nearly all architectures, @code{Machine_Overflows} 21197is False, and IEEE infinities are generated, so overflow exceptions 21198are never raised. If you want to avoid infinities, and check that 21199final results of expressions are in range, then you can declare a 21200constrained floating-point type, and range checks will be carried 21201out in the normal manner (with infinite values always failing all 21202range checks). 21203 21204@node Specifying the Desired Mode,Default Settings,Management of Overflows in GNAT,Overflow Check Handling in GNAT 21205@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9}@anchor{gnat_ugn/gnat_and_program_execution id48}@anchor{1a2} 21206@subsection Specifying the Desired Mode 21207 21208 21209@geindex pragma Overflow_Mode 21210 21211The desired mode of for handling intermediate overflow can be specified using 21212either the @code{Overflow_Mode} pragma or an equivalent compiler switch. 21213The pragma has the form 21214 21215@quotation 21216 21217@example 21218pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]); 21219@end example 21220@end quotation 21221 21222where @code{MODE} is one of 21223 21224 21225@itemize * 21226 21227@item 21228@code{STRICT}: intermediate overflows checked (using base type) 21229 21230@item 21231@code{MINIMIZED}: minimize intermediate overflows 21232 21233@item 21234@code{ELIMINATED}: eliminate intermediate overflows 21235@end itemize 21236 21237The case is ignored, so @code{MINIMIZED}, @code{Minimized} and 21238@code{minimized} all have the same effect. 21239 21240If only the @code{General} parameter is present, then the given @code{MODE} applies 21241to expressions both within and outside assertions. If both arguments 21242are present, then @code{General} applies to expressions outside assertions, 21243and @code{Assertions} applies to expressions within assertions. For example: 21244 21245@quotation 21246 21247@example 21248pragma Overflow_Mode 21249 (General => Minimized, Assertions => Eliminated); 21250@end example 21251@end quotation 21252 21253specifies that general expressions outside assertions be evaluated 21254in 'minimize intermediate overflows' mode, and expressions within 21255assertions be evaluated in 'eliminate intermediate overflows' mode. 21256This is often a reasonable choice, avoiding excessive overhead 21257outside assertions, but assuring a high degree of portability 21258when importing code from another compiler, while incurring 21259the extra overhead for assertion expressions to ensure that 21260the behavior at run time matches the expected mathematical 21261behavior. 21262 21263The @code{Overflow_Mode} pragma has the same scoping and placement 21264rules as pragma @code{Suppress}, so it can occur either as a 21265configuration pragma, specifying a default for the whole 21266program, or in a declarative scope, where it applies to the 21267remaining declarations and statements in that scope. 21268 21269Note that pragma @code{Overflow_Mode} does not affect whether 21270overflow checks are enabled or suppressed. It only controls the 21271method used to compute intermediate values. To control whether 21272overflow checking is enabled or suppressed, use pragma @code{Suppress} 21273or @code{Unsuppress} in the usual manner. 21274 21275@geindex -gnato? (gcc) 21276 21277@geindex -gnato?? (gcc) 21278 21279Additionally, a compiler switch @code{-gnato?} or @code{-gnato??} 21280can be used to control the checking mode default (which can be subsequently 21281overridden using pragmas). 21282 21283Here @code{?} is one of the digits @code{1} through @code{3}: 21284 21285@quotation 21286 21287 21288@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 21289@item 21290 21291@code{1} 21292 21293@tab 21294 21295use base type for intermediate operations (@code{STRICT}) 21296 21297@item 21298 21299@code{2} 21300 21301@tab 21302 21303minimize intermediate overflows (@code{MINIMIZED}) 21304 21305@item 21306 21307@code{3} 21308 21309@tab 21310 21311eliminate intermediate overflows (@code{ELIMINATED}) 21312 21313@end multitable 21314 21315@end quotation 21316 21317As with the pragma, if only one digit appears then it applies to all 21318cases; if two digits are given, then the first applies outside 21319assertions, and the second within assertions. Thus the equivalent 21320of the example pragma above would be 21321@code{-gnato23}. 21322 21323If no digits follow the @code{-gnato}, then it is equivalent to 21324@code{-gnato11}, 21325causing all intermediate operations to be computed using the base 21326type (@code{STRICT} mode). 21327 21328@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT 21329@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1a4} 21330@subsection Default Settings 21331 21332 21333The default mode for overflow checks is 21334 21335@quotation 21336 21337@example 21338General => Strict 21339@end example 21340@end quotation 21341 21342which causes all computations both inside and outside assertions to use 21343the base type. 21344 21345This retains compatibility with previous versions of 21346GNAT which suppressed overflow checks by default and always 21347used the base type for computation of intermediate results. 21348 21349@c Sphinx allows no emphasis within :index: role. As a workaround we 21350@c point the index to "switch" and use emphasis for "-gnato". 21351 21352The 21353@geindex -gnato (gcc) 21354switch @code{-gnato} (with no digits following) 21355is equivalent to 21356 21357@quotation 21358 21359@example 21360General => Strict 21361@end example 21362@end quotation 21363 21364which causes overflow checking of all intermediate overflows 21365both inside and outside assertions against the base type. 21366 21367The pragma @code{Suppress (Overflow_Check)} disables overflow 21368checking, but it has no effect on the method used for computing 21369intermediate results. 21370 21371The pragma @code{Unsuppress (Overflow_Check)} enables overflow 21372checking, but it has no effect on the method used for computing 21373intermediate results. 21374 21375@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT 21376@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1a6} 21377@subsection Implementation Notes 21378 21379 21380In practice on typical 64-bit machines, the @code{MINIMIZED} mode is 21381reasonably efficient, and can be generally used. It also helps 21382to ensure compatibility with code imported from some other 21383compiler to GNAT. 21384 21385Setting all intermediate overflows checking (@code{CHECKED} mode) 21386makes sense if you want to 21387make sure that your code is compatible with any other possible 21388Ada implementation. This may be useful in ensuring portability 21389for code that is to be exported to some other compiler than GNAT. 21390 21391The Ada standard allows the reassociation of expressions at 21392the same precedence level if no parentheses are present. For 21393example, @code{A+B+C} parses as though it were @code{(A+B)+C}, but 21394the compiler can reintepret this as @code{A+(B+C)}, possibly 21395introducing or eliminating an overflow exception. The GNAT 21396compiler never takes advantage of this freedom, and the 21397expression @code{A+B+C} will be evaluated as @code{(A+B)+C}. 21398If you need the other order, you can write the parentheses 21399explicitly @code{A+(B+C)} and GNAT will respect this order. 21400 21401The use of @code{ELIMINATED} mode will cause the compiler to 21402automatically include an appropriate arbitrary precision 21403integer arithmetic package. The compiler will make calls 21404to this package, though only in cases where it cannot be 21405sure that @code{Long_Long_Integer} is sufficient to guard against 21406intermediate overflows. This package does not use dynamic 21407allocation, but it does use the secondary stack, so an 21408appropriate secondary stack package must be present (this 21409is always true for standard full Ada, but may require 21410specific steps for restricted run times such as ZFP). 21411 21412Although @code{ELIMINATED} mode causes expressions to use arbitrary 21413precision arithmetic, avoiding overflow, the final result 21414must be in an appropriate range. This is true even if the 21415final result is of type @code{[Long_[Long_]]Integer'Base}, which 21416still has the same bounds as its associated constrained 21417type at run-time. 21418 21419Currently, the @code{ELIMINATED} mode is only available on target 21420platforms for which @code{Long_Long_Integer} is 64-bits (nearly all GNAT 21421platforms). 21422 21423@node Performing Dimensionality Analysis in GNAT,Stack Related Facilities,Overflow Check Handling in GNAT,GNAT and Program Execution 21424@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution id51}@anchor{14a} 21425@section Performing Dimensionality Analysis in GNAT 21426 21427 21428@geindex Dimensionality analysis 21429 21430The GNAT compiler supports dimensionality checking. The user can 21431specify physical units for objects, and the compiler will verify that uses 21432of these objects are compatible with their dimensions, in a fashion that is 21433familiar to engineering practice. The dimensions of algebraic expressions 21434(including powers with static exponents) are computed from their constituents. 21435 21436@geindex Dimension_System aspect 21437 21438@geindex Dimension aspect 21439 21440This feature depends on Ada 2012 aspect specifications, and is available from 21441version 7.0.1 of GNAT onwards. 21442The GNAT-specific aspect @code{Dimension_System} 21443allows you to define a system of units; the aspect @code{Dimension} 21444then allows the user to declare dimensioned quantities within a given system. 21445(These aspects are described in the @emph{Implementation Defined Aspects} 21446chapter of the @emph{GNAT Reference Manual}). 21447 21448The major advantage of this model is that it does not require the declaration of 21449multiple operators for all possible combinations of types: it is only necessary 21450to use the proper subtypes in object declarations. 21451 21452@geindex System.Dim.Mks package (GNAT library) 21453 21454@geindex MKS_Type type 21455 21456The simplest way to impose dimensionality checking on a computation is to make 21457use of one of the instantiations of the package @code{System.Dim.Generic_Mks}, which 21458are part of the GNAT library. This generic package defines a floating-point 21459type @code{MKS_Type}, for which a sequence of dimension names are specified, 21460together with their conventional abbreviations. The following should be read 21461together with the full specification of the package, in file 21462@code{s-digemk.ads}. 21463 21464@quotation 21465 21466@geindex s-digemk.ads file 21467 21468@example 21469type Mks_Type is new Float_Type 21470 with 21471 Dimension_System => ( 21472 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 21473 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 21474 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 21475 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 21476 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"), 21477 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 21478 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 21479@end example 21480@end quotation 21481 21482The package then defines a series of subtypes that correspond to these 21483conventional units. For example: 21484 21485@quotation 21486 21487@example 21488subtype Length is Mks_Type 21489 with 21490 Dimension => (Symbol => 'm', Meter => 1, others => 0); 21491@end example 21492@end quotation 21493 21494and similarly for @code{Mass}, @code{Time}, @code{Electric_Current}, 21495@code{Thermodynamic_Temperature}, @code{Amount_Of_Substance}, and 21496@code{Luminous_Intensity} (the standard set of units of the SI system). 21497 21498The package also defines conventional names for values of each unit, for 21499example: 21500 21501@quotation 21502 21503@example 21504m : constant Length := 1.0; 21505kg : constant Mass := 1.0; 21506s : constant Time := 1.0; 21507A : constant Electric_Current := 1.0; 21508@end example 21509@end quotation 21510 21511as well as useful multiples of these units: 21512 21513@quotation 21514 21515@example 21516 cm : constant Length := 1.0E-02; 21517 g : constant Mass := 1.0E-03; 21518 min : constant Time := 60.0; 21519 day : constant Time := 60.0 * 24.0 * min; 21520... 21521@end example 21522@end quotation 21523 21524There are three instantiations of @code{System.Dim.Generic_Mks} defined in the 21525GNAT library: 21526 21527 21528@itemize * 21529 21530@item 21531@code{System.Dim.Float_Mks} based on @code{Float} defined in @code{s-diflmk.ads}. 21532 21533@item 21534@code{System.Dim.Long_Mks} based on @code{Long_Float} defined in @code{s-dilomk.ads}. 21535 21536@item 21537@code{System.Dim.Mks} based on @code{Long_Long_Float} defined in @code{s-dimmks.ads}. 21538@end itemize 21539 21540Using one of these packages, you can then define a derived unit by providing 21541the aspect that specifies its dimensions within the MKS system, as well as the 21542string to be used for output of a value of that unit: 21543 21544@quotation 21545 21546@example 21547subtype Acceleration is Mks_Type 21548 with Dimension => ("m/sec^2", 21549 Meter => 1, 21550 Second => -2, 21551 others => 0); 21552@end example 21553@end quotation 21554 21555Here is a complete example of use: 21556 21557@quotation 21558 21559@example 21560with System.Dim.MKS; use System.Dim.Mks; 21561with System.Dim.Mks_IO; use System.Dim.Mks_IO; 21562with Text_IO; use Text_IO; 21563procedure Free_Fall is 21564 subtype Acceleration is Mks_Type 21565 with Dimension => ("m/sec^2", 1, 0, -2, others => 0); 21566 G : constant acceleration := 9.81 * m / (s ** 2); 21567 T : Time := 10.0*s; 21568 Distance : Length; 21569 21570begin 21571 Put ("Gravitational constant: "); 21572 Put (G, Aft => 2, Exp => 0); Put_Line (""); 21573 Distance := 0.5 * G * T ** 2; 21574 Put ("distance travelled in 10 seconds of free fall "); 21575 Put (Distance, Aft => 2, Exp => 0); 21576 Put_Line (""); 21577end Free_Fall; 21578@end example 21579@end quotation 21580 21581Execution of this program yields: 21582 21583@quotation 21584 21585@example 21586Gravitational constant: 9.81 m/sec^2 21587distance travelled in 10 seconds of free fall 490.50 m 21588@end example 21589@end quotation 21590 21591However, incorrect assignments such as: 21592 21593@quotation 21594 21595@example 21596Distance := 5.0; 21597Distance := 5.0 * kg; 21598@end example 21599@end quotation 21600 21601are rejected with the following diagnoses: 21602 21603@quotation 21604 21605@example 21606Distance := 5.0; 21607 >>> dimensions mismatch in assignment 21608 >>> left-hand side has dimension [L] 21609 >>> right-hand side is dimensionless 21610 21611Distance := 5.0 * kg: 21612 >>> dimensions mismatch in assignment 21613 >>> left-hand side has dimension [L] 21614 >>> right-hand side has dimension [M] 21615@end example 21616@end quotation 21617 21618The dimensions of an expression are properly displayed, even if there is 21619no explicit subtype for it. If we add to the program: 21620 21621@quotation 21622 21623@example 21624Put ("Final velocity: "); 21625Put (G * T, Aft =>2, Exp =>0); 21626Put_Line (""); 21627@end example 21628@end quotation 21629 21630then the output includes: 21631 21632@quotation 21633 21634@example 21635Final velocity: 98.10 m.s**(-1) 21636@end example 21637 21638@geindex Dimensionable type 21639 21640@geindex Dimensioned subtype 21641@end quotation 21642 21643The type @code{Mks_Type} is said to be a @emph{dimensionable type} since it has a 21644@code{Dimension_System} aspect, and the subtypes @code{Length}, @code{Mass}, etc., 21645are said to be @emph{dimensioned subtypes} since each one has a @code{Dimension} 21646aspect. 21647 21648@quotation 21649 21650@geindex Dimension Vector (for a dimensioned subtype) 21651 21652@geindex Dimension aspect 21653 21654@geindex Dimension_System aspect 21655@end quotation 21656 21657The @code{Dimension} aspect of a dimensioned subtype @code{S} defines a mapping 21658from the base type's Unit_Names to integer (or, more generally, rational) 21659values. This mapping is the @emph{dimension vector} (also referred to as the 21660@emph{dimensionality}) for that subtype, denoted by @code{DV(S)}, and thus for each 21661object of that subtype. Intuitively, the value specified for each 21662@code{Unit_Name} is the exponent associated with that unit; a zero value 21663means that the unit is not used. For example: 21664 21665@quotation 21666 21667@example 21668declare 21669 Acc : Acceleration; 21670 ... 21671begin 21672 ... 21673end; 21674@end example 21675@end quotation 21676 21677Here @code{DV(Acc)} = @code{DV(Acceleration)} = 21678@code{(Meter=>1, Kilogram=>0, Second=>-2, Ampere=>0, Kelvin=>0, Mole=>0, Candela=>0)}. 21679Symbolically, we can express this as @code{Meter / Second**2}. 21680 21681The dimension vector of an arithmetic expression is synthesized from the 21682dimension vectors of its components, with compile-time dimensionality checks 21683that help prevent mismatches such as using an @code{Acceleration} where a 21684@code{Length} is required. 21685 21686The dimension vector of the result of an arithmetic expression @emph{expr}, or 21687@code{DV(@emph{expr})}, is defined as follows, assuming conventional 21688mathematical definitions for the vector operations that are used: 21689 21690 21691@itemize * 21692 21693@item 21694If @emph{expr} is of the type @emph{universal_real}, or is not of a dimensioned subtype, 21695then @emph{expr} is dimensionless; @code{DV(@emph{expr})} is the empty vector. 21696 21697@item 21698@code{DV(@emph{op expr})}, where @emph{op} is a unary operator, is @code{DV(@emph{expr})} 21699 21700@item 21701@code{DV(@emph{expr1 op expr2})} where @emph{op} is "+" or "-" is @code{DV(@emph{expr1})} 21702provided that @code{DV(@emph{expr1})} = @code{DV(@emph{expr2})}. 21703If this condition is not met then the construct is illegal. 21704 21705@item 21706@code{DV(@emph{expr1} * @emph{expr2})} is @code{DV(@emph{expr1})} + @code{DV(@emph{expr2})}, 21707and @code{DV(@emph{expr1} / @emph{expr2})} = @code{DV(@emph{expr1})} - @code{DV(@emph{expr2})}. 21708In this context if one of the @emph{expr}s is dimensionless then its empty 21709dimension vector is treated as @code{(others => 0)}. 21710 21711@item 21712@code{DV(@emph{expr} ** @emph{power})} is @emph{power} * @code{DV(@emph{expr})}, 21713provided that @emph{power} is a static rational value. If this condition is not 21714met then the construct is illegal. 21715@end itemize 21716 21717Note that, by the above rules, it is illegal to use binary "+" or "-" to 21718combine a dimensioned and dimensionless value. Thus an expression such as 21719@code{acc-10.0} is illegal, where @code{acc} is an object of subtype 21720@code{Acceleration}. 21721 21722The dimensionality checks for relationals use the same rules as 21723for "+" and "-", except when comparing to a literal; thus 21724 21725@quotation 21726 21727@example 21728acc > len 21729@end example 21730@end quotation 21731 21732is equivalent to 21733 21734@quotation 21735 21736@example 21737acc-len > 0.0 21738@end example 21739@end quotation 21740 21741and is thus illegal, but 21742 21743@quotation 21744 21745@example 21746acc > 10.0 21747@end example 21748@end quotation 21749 21750is accepted with a warning. Analogously a conditional expression requires the 21751same dimension vector for each branch (with no exception for literals). 21752 21753The dimension vector of a type conversion @code{T(@emph{expr})} is defined 21754as follows, based on the nature of @code{T}: 21755 21756 21757@itemize * 21758 21759@item 21760If @code{T} is a dimensioned subtype then @code{DV(T(@emph{expr}))} is @code{DV(T)} 21761provided that either @emph{expr} is dimensionless or 21762@code{DV(T)} = @code{DV(@emph{expr})}. The conversion is illegal 21763if @emph{expr} is dimensioned and @code{DV(@emph{expr})} /= @code{DV(T)}. 21764Note that vector equality does not require that the corresponding 21765Unit_Names be the same. 21766 21767As a consequence of the above rule, it is possible to convert between 21768different dimension systems that follow the same international system 21769of units, with the seven physical components given in the standard order 21770(length, mass, time, etc.). Thus a length in meters can be converted to 21771a length in inches (with a suitable conversion factor) but cannot be 21772converted, for example, to a mass in pounds. 21773 21774@item 21775If @code{T} is the base type for @emph{expr} (and the dimensionless root type of 21776the dimension system), then @code{DV(T(@emph{expr}))} is @code{DV(expr)}. 21777Thus, if @emph{expr} is of a dimensioned subtype of @code{T}, the conversion may 21778be regarded as a "view conversion" that preserves dimensionality. 21779 21780This rule makes it possible to write generic code that can be instantiated 21781with compatible dimensioned subtypes. The generic unit will contain 21782conversions that will consequently be present in instantiations, but 21783conversions to the base type will preserve dimensionality and make it 21784possible to write generic code that is correct with respect to 21785dimensionality. 21786 21787@item 21788Otherwise (i.e., @code{T} is neither a dimensioned subtype nor a dimensionable 21789base type), @code{DV(T(@emph{expr}))} is the empty vector. Thus a dimensioned 21790value can be explicitly converted to a non-dimensioned subtype, which 21791of course then escapes dimensionality analysis. 21792@end itemize 21793 21794The dimension vector for a type qualification @code{T'(@emph{expr})} is the same 21795as for the type conversion @code{T(@emph{expr})}. 21796 21797An assignment statement 21798 21799@quotation 21800 21801@example 21802Source := Target; 21803@end example 21804@end quotation 21805 21806requires @code{DV(Source)} = @code{DV(Target)}, and analogously for parameter 21807passing (the dimension vector for the actual parameter must be equal to the 21808dimension vector for the formal parameter). 21809 21810@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution 21811@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1a8}@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{14b} 21812@section Stack Related Facilities 21813 21814 21815This section describes some useful tools associated with stack 21816checking and analysis. In 21817particular, it deals with dynamic and static stack usage measurements. 21818 21819@menu 21820* Stack Overflow Checking:: 21821* Static Stack Usage Analysis:: 21822* Dynamic Stack Usage Analysis:: 21823 21824@end menu 21825 21826@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities 21827@anchor{gnat_ugn/gnat_and_program_execution id53}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{e5} 21828@subsection Stack Overflow Checking 21829 21830 21831@geindex Stack Overflow Checking 21832 21833@geindex -fstack-check (gcc) 21834 21835For most operating systems, @code{gcc} does not perform stack overflow 21836checking by default. This means that if the main environment task or 21837some other task exceeds the available stack space, then unpredictable 21838behavior will occur. Most native systems offer some level of protection by 21839adding a guard page at the end of each task stack. This mechanism is usually 21840not enough for dealing properly with stack overflow situations because 21841a large local variable could "jump" above the guard page. 21842Furthermore, when the 21843guard page is hit, there may not be any space left on the stack for executing 21844the exception propagation code. Enabling stack checking avoids 21845such situations. 21846 21847To activate stack checking, compile all units with the @code{gcc} option 21848@code{-fstack-check}. For example: 21849 21850@quotation 21851 21852@example 21853$ gcc -c -fstack-check package1.adb 21854@end example 21855@end quotation 21856 21857Units compiled with this option will generate extra instructions to check 21858that any use of the stack (for procedure calls or for declaring local 21859variables in declare blocks) does not exceed the available stack space. 21860If the space is exceeded, then a @code{Storage_Error} exception is raised. 21861 21862For declared tasks, the default stack size is defined by the GNAT runtime, 21863whose size may be modified at bind time through the @code{-d} bind switch 21864(@ref{110,,Switches for gnatbind}). Task specific stack sizes may be set using the 21865@code{Storage_Size} pragma. 21866 21867For the environment task, the stack size is determined by the operating system. 21868Consequently, to modify the size of the environment task please refer to your 21869operating system documentation. 21870 21871@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities 21872@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6} 21873@subsection Static Stack Usage Analysis 21874 21875 21876@geindex Static Stack Usage Analysis 21877 21878@geindex -fstack-usage 21879 21880A unit compiled with @code{-fstack-usage} will generate an extra file 21881that specifies 21882the maximum amount of stack used, on a per-function basis. 21883The file has the same 21884basename as the target object file with a @code{.su} extension. 21885Each line of this file is made up of three fields: 21886 21887 21888@itemize * 21889 21890@item 21891The name of the function. 21892 21893@item 21894A number of bytes. 21895 21896@item 21897One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. 21898@end itemize 21899 21900The second field corresponds to the size of the known part of the function 21901frame. 21902 21903The qualifier @code{static} means that the function frame size 21904is purely static. 21905It usually means that all local variables have a static size. 21906In this case, the second field is a reliable measure of the function stack 21907utilization. 21908 21909The qualifier @code{dynamic} means that the function frame size is not static. 21910It happens mainly when some local variables have a dynamic size. When this 21911qualifier appears alone, the second field is not a reliable measure 21912of the function stack analysis. When it is qualified with @code{bounded}, it 21913means that the second field is a reliable maximum of the function stack 21914utilization. 21915 21916A unit compiled with @code{-Wstack-usage} will issue a warning for each 21917subprogram whose stack usage might be larger than the specified amount of 21918bytes. The wording is in keeping with the qualifier documented above. 21919 21920@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities 21921@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1ab}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{113} 21922@subsection Dynamic Stack Usage Analysis 21923 21924 21925It is possible to measure the maximum amount of stack used by a task, by 21926adding a switch to @code{gnatbind}, as: 21927 21928@quotation 21929 21930@example 21931$ gnatbind -u0 file 21932@end example 21933@end quotation 21934 21935With this option, at each task termination, its stack usage is output on 21936@code{stderr}. 21937Note that this switch is not compatible with tools like 21938Valgrind and DrMemory; they will report errors. 21939 21940It is not always convenient to output the stack usage when the program 21941is still running. Hence, it is possible to delay this output until program 21942termination. for a given number of tasks specified as the argument of the 21943@code{-u} option. For instance: 21944 21945@quotation 21946 21947@example 21948$ gnatbind -u100 file 21949@end example 21950@end quotation 21951 21952will buffer the stack usage information of the first 100 tasks to terminate and 21953output this info at program termination. Results are displayed in four 21954columns: 21955 21956@quotation 21957 21958@example 21959Index | Task Name | Stack Size | Stack Usage 21960@end example 21961@end quotation 21962 21963where: 21964 21965 21966@itemize * 21967 21968@item 21969@emph{Index} is a number associated with each task. 21970 21971@item 21972@emph{Task Name} is the name of the task analyzed. 21973 21974@item 21975@emph{Stack Size} is the maximum size for the stack. 21976 21977@item 21978@emph{Stack Usage} is the measure done by the stack analyzer. 21979In order to prevent overflow, the stack 21980is not entirely analyzed, and it's not possible to know exactly how 21981much has actually been used. 21982@end itemize 21983 21984By default the environment task stack, the stack that contains the main unit, 21985is not processed. To enable processing of the environment task stack, the 21986environment variable GNAT_STACK_LIMIT needs to be set to the maximum size of 21987the environment task stack. This amount is given in kilobytes. For example: 21988 21989@quotation 21990 21991@example 21992$ set GNAT_STACK_LIMIT 1600 21993@end example 21994@end quotation 21995 21996would specify to the analyzer that the environment task stack has a limit 21997of 1.6 megabytes. Any stack usage beyond this will be ignored by the analysis. 21998 21999The package @code{GNAT.Task_Stack_Usage} provides facilities to get 22000stack-usage reports at run time. See its body for the details. 22001 22002@node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution 22003@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{14c}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1ac} 22004@section Memory Management Issues 22005 22006 22007This section describes some useful memory pools provided in the GNAT library 22008and in particular the GNAT Debug Pool facility, which can be used to detect 22009incorrect uses of access values (including 'dangling references'). 22010 22011 22012@menu 22013* Some Useful Memory Pools:: 22014* The GNAT Debug Pool Facility:: 22015 22016@end menu 22017 22018@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues 22019@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1ad}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ae} 22020@subsection Some Useful Memory Pools 22021 22022 22023@geindex Memory Pool 22024 22025@geindex storage 22026@geindex pool 22027 22028The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool 22029storage pool. Allocations use the standard system call @code{malloc} while 22030deallocations use the standard system call @code{free}. No reclamation is 22031performed when the pool goes out of scope. For performance reasons, the 22032standard default Ada allocators/deallocators do not use any explicit storage 22033pools but if they did, they could use this storage pool without any change in 22034behavior. That is why this storage pool is used when the user 22035manages to make the default implicit allocator explicit as in this example: 22036 22037@quotation 22038 22039@example 22040type T1 is access Something; 22041 -- no Storage pool is defined for T2 22042 22043type T2 is access Something_Else; 22044for T2'Storage_Pool use T1'Storage_Pool; 22045-- the above is equivalent to 22046for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; 22047@end example 22048@end quotation 22049 22050The @code{System.Pool_Local} package offers the @code{Unbounded_Reclaim_Pool} storage 22051pool. The allocation strategy is similar to @code{Pool_Local} 22052except that the all 22053storage allocated with this pool is reclaimed when the pool object goes out of 22054scope. This pool provides a explicit mechanism similar to the implicit one 22055provided by several Ada 83 compilers for allocations performed through a local 22056access type and whose purpose was to reclaim memory when exiting the 22057scope of a given local access. As an example, the following program does not 22058leak memory even though it does not perform explicit deallocation: 22059 22060@quotation 22061 22062@example 22063with System.Pool_Local; 22064procedure Pooloc1 is 22065 procedure Internal is 22066 type A is access Integer; 22067 X : System.Pool_Local.Unbounded_Reclaim_Pool; 22068 for A'Storage_Pool use X; 22069 v : A; 22070 begin 22071 for I in 1 .. 50 loop 22072 v := new Integer; 22073 end loop; 22074 end Internal; 22075begin 22076 for I in 1 .. 100 loop 22077 Internal; 22078 end loop; 22079end Pooloc1; 22080@end example 22081@end quotation 22082 22083The @code{System.Pool_Size} package implements the @code{Stack_Bounded_Pool} used when 22084@code{Storage_Size} is specified for an access type. 22085The whole storage for the pool is 22086allocated at once, usually on the stack at the point where the access type is 22087elaborated. It is automatically reclaimed when exiting the scope where the 22088access type is defined. This package is not intended to be used directly by the 22089user and it is implicitly used for each such declaration: 22090 22091@quotation 22092 22093@example 22094type T1 is access Something; 22095for T1'Storage_Size use 10_000; 22096@end example 22097@end quotation 22098 22099@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues 22100@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1b0} 22101@subsection The GNAT Debug Pool Facility 22102 22103 22104@geindex Debug Pool 22105 22106@geindex storage 22107@geindex pool 22108@geindex memory corruption 22109 22110The use of unchecked deallocation and unchecked conversion can easily 22111lead to incorrect memory references. The problems generated by such 22112references are usually difficult to tackle because the symptoms can be 22113very remote from the origin of the problem. In such cases, it is 22114very helpful to detect the problem as early as possible. This is the 22115purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}. 22116 22117In order to use the GNAT specific debugging pool, the user must 22118associate a debug pool object with each of the access types that may be 22119related to suspected memory problems. See Ada Reference Manual 13.11. 22120 22121@quotation 22122 22123@example 22124type Ptr is access Some_Type; 22125Pool : GNAT.Debug_Pools.Debug_Pool; 22126for Ptr'Storage_Pool use Pool; 22127@end example 22128@end quotation 22129 22130@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of 22131pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools, 22132allow the user to redefine allocation and deallocation strategies. They 22133also provide a checkpoint for each dereference, through the use of 22134the primitive operation @code{Dereference} which is implicitly called at 22135each dereference of an access value. 22136 22137Once an access type has been associated with a debug pool, operations on 22138values of the type may raise four distinct exceptions, 22139which correspond to four potential kinds of memory corruption: 22140 22141 22142@itemize * 22143 22144@item 22145@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage} 22146 22147@item 22148@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage} 22149 22150@item 22151@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage} 22152 22153@item 22154@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage} 22155@end itemize 22156 22157For types associated with a Debug_Pool, dynamic allocation is performed using 22158the standard GNAT allocation routine. References to all allocated chunks of 22159memory are kept in an internal dictionary. Several deallocation strategies are 22160provided, whereupon the user can choose to release the memory to the system, 22161keep it allocated for further invalid access checks, or fill it with an easily 22162recognizable pattern for debug sessions. The memory pattern is the old IBM 22163hexadecimal convention: @code{16#DEADBEEF#}. 22164 22165See the documentation in the file g-debpoo.ads for more information on the 22166various strategies. 22167 22168Upon each dereference, a check is made that the access value denotes a 22169properly allocated memory location. Here is a complete example of use of 22170@code{Debug_Pools}, that includes typical instances of memory corruption: 22171 22172@quotation 22173 22174@example 22175with Gnat.Io; use Gnat.Io; 22176with Unchecked_Deallocation; 22177with Unchecked_Conversion; 22178with GNAT.Debug_Pools; 22179with System.Storage_Elements; 22180with Ada.Exceptions; use Ada.Exceptions; 22181procedure Debug_Pool_Test is 22182 22183 type T is access Integer; 22184 type U is access all T; 22185 22186 P : GNAT.Debug_Pools.Debug_Pool; 22187 for T'Storage_Pool use P; 22188 22189 procedure Free is new Unchecked_Deallocation (Integer, T); 22190 function UC is new Unchecked_Conversion (U, T); 22191 A, B : aliased T; 22192 22193 procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); 22194 22195begin 22196 Info (P); 22197 A := new Integer; 22198 B := new Integer; 22199 B := A; 22200 Info (P); 22201 Free (A); 22202 begin 22203 Put_Line (Integer'Image(B.all)); 22204 exception 22205 when E : others => Put_Line ("raised: " & Exception_Name (E)); 22206 end; 22207 begin 22208 Free (B); 22209 exception 22210 when E : others => Put_Line ("raised: " & Exception_Name (E)); 22211 end; 22212 B := UC(A'Access); 22213 begin 22214 Put_Line (Integer'Image(B.all)); 22215 exception 22216 when E : others => Put_Line ("raised: " & Exception_Name (E)); 22217 end; 22218 begin 22219 Free (B); 22220 exception 22221 when E : others => Put_Line ("raised: " & Exception_Name (E)); 22222 end; 22223 Info (P); 22224end Debug_Pool_Test; 22225@end example 22226@end quotation 22227 22228The debug pool mechanism provides the following precise diagnostics on the 22229execution of this erroneous program: 22230 22231@quotation 22232 22233@example 22234Debug Pool info: 22235 Total allocated bytes : 0 22236 Total deallocated bytes : 0 22237 Current Water Mark: 0 22238 High Water Mark: 0 22239 22240Debug Pool info: 22241 Total allocated bytes : 8 22242 Total deallocated bytes : 0 22243 Current Water Mark: 8 22244 High Water Mark: 8 22245 22246raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE 22247raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE 22248raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE 22249raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE 22250Debug Pool info: 22251 Total allocated bytes : 8 22252 Total deallocated bytes : 4 22253 Current Water Mark: 4 22254 High Water Mark: 8 22255@end example 22256@end quotation 22257 22258 22259@c -- Non-breaking space in running text 22260@c -- E.g. Ada |nbsp| 95 22261 22262@node Platform-Specific Information,Example of Binder Output File,GNAT and Program Execution,Top 22263@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2} 22264@chapter Platform-Specific Information 22265 22266 22267This appendix contains information relating to the implementation 22268of run-time libraries on various platforms and also covers 22269topics related to the GNAT implementation on Windows and Mac OS. 22270 22271@menu 22272* Run-Time Libraries:: 22273* Specifying a Run-Time Library:: 22274* GNU/Linux Topics:: 22275* Microsoft Windows Topics:: 22276* Mac OS Topics:: 22277 22278@end menu 22279 22280@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information 22281@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4} 22282@section Run-Time Libraries 22283 22284 22285@geindex Tasking and threads libraries 22286 22287@geindex Threads libraries and tasking 22288 22289@geindex Run-time libraries (platform-specific information) 22290 22291The GNAT run-time implementation may vary with respect to both the 22292underlying threads library and the exception-handling scheme. 22293For threads support, the default run-time will bind to the thread 22294package of the underlying operating system. 22295 22296For exception handling, either or both of two models are supplied: 22297 22298@quotation 22299 22300@geindex Zero-Cost Exceptions 22301 22302@geindex ZCX (Zero-Cost Exceptions) 22303@end quotation 22304 22305 22306@itemize * 22307 22308@item 22309@strong{Zero-Cost Exceptions} ("ZCX"), 22310which uses binder-generated tables that 22311are interrogated at run time to locate a handler. 22312 22313@geindex setjmp/longjmp Exception Model 22314 22315@geindex SJLJ (setjmp/longjmp Exception Model) 22316 22317@item 22318@strong{setjmp / longjmp} ('SJLJ'), 22319which uses dynamically-set data to establish 22320the set of handlers 22321@end itemize 22322 22323Most programs should experience a substantial speed improvement by 22324being compiled with a ZCX run-time. 22325This is especially true for 22326tasking applications or applications with many exception handlers. 22327Note however that the ZCX run-time does not support asynchronous abort 22328of tasks (@code{abort} and @code{select-then-abort} constructs) and will instead 22329implement abort by polling points in the runtime. You can also add additional 22330polling points explicitly if needed in your application via @code{pragma 22331Abort_Defer}. 22332 22333This section summarizes which combinations of threads and exception support 22334are supplied on various GNAT platforms. 22335 22336@menu 22337* Summary of Run-Time Configurations:: 22338 22339@end menu 22340 22341@node Summary of Run-Time Configurations,,,Run-Time Libraries 22342@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1b5}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1b6} 22343@subsection Summary of Run-Time Configurations 22344 22345 22346 22347@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 22348@headitem 22349 22350Platform 22351 22352@tab 22353 22354Run-Time 22355 22356@tab 22357 22358Tasking 22359 22360@tab 22361 22362Exceptions 22363 22364@item 22365 22366GNU/Linux 22367 22368@tab 22369 22370rts-native 22371(default) 22372 22373@tab 22374 22375pthread library 22376 22377@tab 22378 22379ZCX 22380 22381@item 22382 22383rts-sjlj 22384 22385@tab 22386 22387pthread library 22388 22389@tab 22390 22391SJLJ 22392 22393@item 22394 22395Windows 22396 22397@tab 22398 22399rts-native 22400(default) 22401 22402@tab 22403 22404native Win32 threads 22405 22406@tab 22407 22408ZCX 22409 22410@item 22411 22412rts-sjlj 22413 22414@tab 22415 22416native Win32 threads 22417 22418@tab 22419 22420SJLJ 22421 22422@item 22423 22424Mac OS 22425 22426@tab 22427 22428rts-native 22429 22430@tab 22431 22432pthread library 22433 22434@tab 22435 22436ZCX 22437 22438@end multitable 22439 22440 22441@node Specifying a Run-Time Library,GNU/Linux Topics,Run-Time Libraries,Platform-Specific Information 22442@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1b7}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b8} 22443@section Specifying a Run-Time Library 22444 22445 22446The @code{adainclude} subdirectory containing the sources of the GNAT 22447run-time library, and the @code{adalib} subdirectory containing the 22448@code{ALI} files and the static and/or shared GNAT library, are located 22449in the gcc target-dependent area: 22450 22451@quotation 22452 22453@example 22454target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/ 22455@end example 22456@end quotation 22457 22458As indicated above, on some platforms several run-time libraries are supplied. 22459These libraries are installed in the target dependent area and 22460contain a complete source and binary subdirectory. The detailed description 22461below explains the differences between the different libraries in terms of 22462their thread support. 22463 22464The default run-time library (when GNAT is installed) is @emph{rts-native}. 22465This default run-time is selected by the means of soft links. 22466For example on x86-linux: 22467 22468@c -- 22469@c -- $(target-dir) 22470@c -- | 22471@c -- +--- adainclude----------+ 22472@c -- | | 22473@c -- +--- adalib-----------+ | 22474@c -- | | | 22475@c -- +--- rts-native | | 22476@c -- | | | | 22477@c -- | +--- adainclude <---+ 22478@c -- | | | 22479@c -- | +--- adalib <----+ 22480@c -- | 22481@c -- +--- rts-sjlj 22482@c -- | 22483@c -- +--- adainclude 22484@c -- | 22485@c -- +--- adalib 22486 22487 22488@example 22489 $(target-dir) 22490 __/ / \ \___ 22491 _______/ / \ \_________________ 22492 / / \ \ 22493 / / \ \ 22494ADAINCLUDE ADALIB rts-native rts-sjlj 22495 : : / \ / \ 22496 : : / \ / \ 22497 : : / \ / \ 22498 : : / \ / \ 22499 +-------------> adainclude adalib adainclude adalib 22500 : ^ 22501 : : 22502 +---------------------+ 22503 22504 Run-Time Library Directory Structure 22505 (Upper-case names and dotted/dashed arrows represent soft links) 22506@end example 22507 22508If the @emph{rts-sjlj} library is to be selected on a permanent basis, 22509these soft links can be modified with the following commands: 22510 22511@quotation 22512 22513@example 22514$ cd $target 22515$ rm -f adainclude adalib 22516$ ln -s rts-sjlj/adainclude adainclude 22517$ ln -s rts-sjlj/adalib adalib 22518@end example 22519@end quotation 22520 22521Alternatively, you can specify @code{rts-sjlj/adainclude} in the file 22522@code{$target/ada_source_path} and @code{rts-sjlj/adalib} in 22523@code{$target/ada_object_path}. 22524 22525@geindex --RTS option 22526 22527Selecting another run-time library temporarily can be 22528achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj} 22529@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1b9} 22530@geindex SCHED_FIFO scheduling policy 22531 22532@geindex SCHED_RR scheduling policy 22533 22534@geindex SCHED_OTHER scheduling policy 22535 22536@menu 22537* Choosing the Scheduling Policy:: 22538 22539@end menu 22540 22541@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library 22542@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba} 22543@subsection Choosing the Scheduling Policy 22544 22545 22546When using a POSIX threads implementation, you have a choice of several 22547scheduling policies: @code{SCHED_FIFO}, @code{SCHED_RR} and @code{SCHED_OTHER}. 22548 22549Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO} 22550or @code{SCHED_RR} requires special (e.g., root) privileges. 22551 22552@geindex pragma Time_Slice 22553 22554@geindex -T0 option 22555 22556@geindex pragma Task_Dispatching_Policy 22557 22558By default, GNAT uses the @code{SCHED_OTHER} policy. To specify 22559@code{SCHED_FIFO}, 22560you can use one of the following: 22561 22562 22563@itemize * 22564 22565@item 22566@code{pragma Time_Slice (0.0)} 22567 22568@item 22569the corresponding binder option @code{-T0} 22570 22571@item 22572@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} 22573@end itemize 22574 22575To specify @code{SCHED_RR}, 22576you should use @code{pragma Time_Slice} with a 22577value greater than 0.0, or else use the corresponding @code{-T} 22578binder option. 22579 22580To make sure a program is running as root, you can put something like 22581this in a library package body in your application: 22582 22583@quotation 22584 22585@example 22586function geteuid return Integer; 22587pragma Import (C, geteuid, "geteuid"); 22588Ignore : constant Boolean := 22589 (if geteuid = 0 then True else raise Program_Error with "must be root"); 22590@end example 22591@end quotation 22592 22593It gets the effective user id, and if it's not 0 (i.e. root), it raises 22594Program_Error. 22595 22596@geindex Linux 22597 22598@geindex GNU/Linux 22599 22600@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information 22601@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bc} 22602@section GNU/Linux Topics 22603 22604 22605This section describes topics that are specific to GNU/Linux platforms. 22606 22607@menu 22608* Required Packages on GNU/Linux:: 22609 22610@end menu 22611 22612@node Required Packages on GNU/Linux,,,GNU/Linux Topics 22613@anchor{gnat_ugn/platform_specific_information id7}@anchor{1bd}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1be} 22614@subsection Required Packages on GNU/Linux 22615 22616 22617GNAT requires the C library developer's package to be installed. 22618The name of of that package depends on your GNU/Linux distribution: 22619 22620 22621@itemize * 22622 22623@item 22624RedHat, SUSE: @code{glibc-devel}; 22625 22626@item 22627Debian, Ubuntu: @code{libc6-dev} (normally installed by default). 22628@end itemize 22629 22630If using the 32-bit version of GNAT on a 64-bit version of GNU/Linux, 22631you'll need the 32-bit version of the following packages: 22632 22633 22634@itemize * 22635 22636@item 22637RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}, @code{ncurses-libs.i686} 22638 22639@item 22640Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}, @code{lib32ncursesw5} 22641@end itemize 22642 22643Other GNU/Linux distributions might be choosing a different name 22644for those packages. 22645 22646@geindex Windows 22647 22648@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information 22649@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0} 22650@section Microsoft Windows Topics 22651 22652 22653This section describes topics that are specific to the Microsoft Windows 22654platforms. 22655 22656 22657@menu 22658* Using GNAT on Windows:: 22659* Using a network installation of GNAT:: 22660* CONSOLE and WINDOWS subsystems:: 22661* Temporary Files:: 22662* Disabling Command Line Argument Expansion:: 22663* Windows Socket Timeouts:: 22664* Mixed-Language Programming on Windows:: 22665* Windows Specific Add-Ons:: 22666 22667@end menu 22668 22669@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics 22670@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1c1}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c2} 22671@subsection Using GNAT on Windows 22672 22673 22674One of the strengths of the GNAT technology is that its tool set 22675(@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the 22676@code{gdb} debugger, etc.) is used in the same way regardless of the 22677platform. 22678 22679On Windows this tool set is complemented by a number of Microsoft-specific 22680tools that have been provided to facilitate interoperability with Windows 22681when this is required. With these tools: 22682 22683 22684@itemize * 22685 22686@item 22687You can build applications using the @code{CONSOLE} or @code{WINDOWS} 22688subsystems. 22689 22690@item 22691You can use any Dynamically Linked Library (DLL) in your Ada code (both 22692relocatable and non-relocatable DLLs are supported). 22693 22694@item 22695You can build Ada DLLs for use in other applications. These applications 22696can be written in a language other than Ada (e.g., C, C++, etc). Again both 22697relocatable and non-relocatable Ada DLLs are supported. 22698 22699@item 22700You can include Windows resources in your Ada application. 22701 22702@item 22703You can use or create COM/DCOM objects. 22704@end itemize 22705 22706Immediately below are listed all known general GNAT-for-Windows restrictions. 22707Other restrictions about specific features like Windows Resources and DLLs 22708are listed in separate sections below. 22709 22710 22711@itemize * 22712 22713@item 22714It is not possible to use @code{GetLastError} and @code{SetLastError} 22715when tasking, protected records, or exceptions are used. In these 22716cases, in order to implement Ada semantics, the GNAT run-time system 22717calls certain Win32 routines that set the last error variable to 0 upon 22718success. It should be possible to use @code{GetLastError} and 22719@code{SetLastError} when tasking, protected record, and exception 22720features are not used, but it is not guaranteed to work. 22721 22722@item 22723It is not possible to link against Microsoft C++ libraries except for 22724import libraries. Interfacing must be done by the mean of DLLs. 22725 22726@item 22727It is possible to link against Microsoft C libraries. Yet the preferred 22728solution is to use C/C++ compiler that comes with GNAT, since it 22729doesn't require having two different development environments and makes the 22730inter-language debugging experience smoother. 22731 22732@item 22733When the compilation environment is located on FAT32 drives, users may 22734experience recompilations of the source files that have not changed if 22735Daylight Saving Time (DST) state has changed since the last time files 22736were compiled. NTFS drives do not have this problem. 22737 22738@item 22739No components of the GNAT toolset use any entries in the Windows 22740registry. The only entries that can be created are file associations and 22741PATH settings, provided the user has chosen to create them at installation 22742time, as well as some minimal book-keeping information needed to correctly 22743uninstall or integrate different GNAT products. 22744@end itemize 22745 22746@node Using a network installation of GNAT,CONSOLE and WINDOWS subsystems,Using GNAT on Windows,Microsoft Windows Topics 22747@anchor{gnat_ugn/platform_specific_information id10}@anchor{1c3}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c4} 22748@subsection Using a network installation of GNAT 22749 22750 22751Make sure the system on which GNAT is installed is accessible from the 22752current machine, i.e., the install location is shared over the network. 22753Shared resources are accessed on Windows by means of UNC paths, which 22754have the format @code{\\\\server\\sharename\\path} 22755 22756In order to use such a network installation, simply add the UNC path of the 22757@code{bin} directory of your GNAT installation in front of your PATH. For 22758example, if GNAT is installed in @code{\GNAT} directory of a share location 22759called @code{c-drive} on a machine @code{LOKI}, the following command will 22760make it available: 22761 22762@quotation 22763 22764@example 22765$ path \\loki\c-drive\gnat\bin;%path%` 22766@end example 22767@end quotation 22768 22769Be aware that every compilation using the network installation results in the 22770transfer of large amounts of data across the network and will likely cause 22771serious performance penalty. 22772 22773@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics 22774@anchor{gnat_ugn/platform_specific_information id11}@anchor{1c5}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1c6} 22775@subsection CONSOLE and WINDOWS subsystems 22776 22777 22778@geindex CONSOLE Subsystem 22779 22780@geindex WINDOWS Subsystem 22781 22782@geindex -mwindows 22783 22784There are two main subsystems under Windows. The @code{CONSOLE} subsystem 22785(which is the default subsystem) will always create a console when 22786launching the application. This is not something desirable when the 22787application has a Windows GUI. To get rid of this console the 22788application must be using the @code{WINDOWS} subsystem. To do so 22789the @code{-mwindows} linker option must be specified. 22790 22791@quotation 22792 22793@example 22794$ gnatmake winprog -largs -mwindows 22795@end example 22796@end quotation 22797 22798@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics 22799@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1c8} 22800@subsection Temporary Files 22801 22802 22803@geindex Temporary files 22804 22805It is possible to control where temporary files gets created by setting 22806the 22807@geindex TMP 22808@geindex environment variable; TMP 22809@code{TMP} environment variable. The file will be created: 22810 22811 22812@itemize * 22813 22814@item 22815Under the directory pointed to by the 22816@geindex TMP 22817@geindex environment variable; TMP 22818@code{TMP} environment variable if 22819this directory exists. 22820 22821@item 22822Under @code{c:\temp}, if the 22823@geindex TMP 22824@geindex environment variable; TMP 22825@code{TMP} environment variable is not 22826set (or not pointing to a directory) and if this directory exists. 22827 22828@item 22829Under the current working directory otherwise. 22830@end itemize 22831 22832This allows you to determine exactly where the temporary 22833file will be created. This is particularly useful in networked 22834environments where you may not have write access to some 22835directories. 22836 22837@node Disabling Command Line Argument Expansion,Windows Socket Timeouts,Temporary Files,Microsoft Windows Topics 22838@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1c9} 22839@subsection Disabling Command Line Argument Expansion 22840 22841 22842@geindex Command Line Argument Expansion 22843 22844By default, an executable compiled for the Windows platform will do 22845the following postprocessing on the arguments passed on the command 22846line: 22847 22848 22849@itemize * 22850 22851@item 22852If the argument contains the characters @code{*} and/or @code{?}, then 22853file expansion will be attempted. For example, if the current directory 22854contains @code{a.txt} and @code{b.txt}, then when calling: 22855 22856@example 22857$ my_ada_program *.txt 22858@end example 22859 22860The following arguments will effectively be passed to the main program 22861(for example when using @code{Ada.Command_Line.Argument}): 22862 22863@example 22864Ada.Command_Line.Argument (1) -> "a.txt" 22865Ada.Command_Line.Argument (2) -> "b.txt" 22866@end example 22867 22868@item 22869Filename expansion can be disabled for a given argument by using single 22870quotes. Thus, calling: 22871 22872@example 22873$ my_ada_program '*.txt' 22874@end example 22875 22876will result in: 22877 22878@example 22879Ada.Command_Line.Argument (1) -> "*.txt" 22880@end example 22881@end itemize 22882 22883Note that if the program is launched from a shell such as Cygwin Bash 22884then quote removal might be performed by the shell. 22885 22886In some contexts it might be useful to disable this feature (for example if 22887the program performs its own argument expansion). In order to do this, a C 22888symbol needs to be defined and set to @code{0}. You can do this by 22889adding the following code fragment in one of your Ada units: 22890 22891@example 22892Do_Argv_Expansion : Integer := 0; 22893pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion"); 22894@end example 22895 22896The results of previous examples will be respectively: 22897 22898@example 22899Ada.Command_Line.Argument (1) -> "*.txt" 22900@end example 22901 22902and: 22903 22904@example 22905Ada.Command_Line.Argument (1) -> "'*.txt'" 22906@end example 22907 22908@node Windows Socket Timeouts,Mixed-Language Programming on Windows,Disabling Command Line Argument Expansion,Microsoft Windows Topics 22909@anchor{gnat_ugn/platform_specific_information windows-socket-timeouts}@anchor{1ca} 22910@subsection Windows Socket Timeouts 22911 22912 22913Microsoft Windows desktops older than @code{8.0} and Microsoft Windows Servers 22914older than @code{2019} set a socket timeout 500 milliseconds longer than the value 22915set by setsockopt with @code{SO_RCVTIMEO} and @code{SO_SNDTIMEO} options. The GNAT 22916runtime makes a correction for the difference in the corresponding Windows 22917versions. For Windows Server starting with version @code{2019}, the user must 22918provide a manifest file for the GNAT runtime to be able to recognize that 22919the Windows version does not need the timeout correction. The manifest file 22920should be located in the same directory as the executable file, and its file 22921name must match the executable name suffixed by @code{.manifest}. For example, 22922if the executable name is @code{sock_wto.exe}, then the manifest file name 22923has to be @code{sock_wto.exe.manifest}. The manifest file must contain at 22924least the following data: 22925 22926@example 22927<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 22928<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> 22929<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1"> 22930<application> 22931 <!-- Windows Vista --> 22932 <supportedOS Id="@{e2011457-1546-43c5-a5fe-008deee3d3f0@}"/> 22933 <!-- Windows 7 --> 22934 <supportedOS Id="@{35138b9a-5d96-4fbd-8e2d-a2440225f93a@}"/> 22935 <!-- Windows 8 --> 22936 <supportedOS Id="@{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38@}"/> 22937 <!-- Windows 8.1 --> 22938 <supportedOS Id="@{1f676c76-80e1-4239-95bb-83d0f6d0da78@}"/> 22939 <!-- Windows 10 --> 22940 <supportedOS Id="@{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a@}"/> 22941</application> 22942</compatibility> 22943</assembly> 22944@end example 22945 22946Without the manifest file, the socket timeout is going to be overcorrected on 22947these Windows Server versions and the actual time is going to be 500 22948milliseconds shorter than what was set with GNAT.Sockets.Set_Socket_Option. 22949Note that on Microsoft Windows versions where correction is necessary, there 22950is no way to set a socket timeout shorter than 500 ms. If a socket timeout 22951shorter than 500 ms is needed on these Windows versions, a call to 22952Check_Selector should be added before any socket read or write operations. 22953 22954@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Windows Socket Timeouts,Microsoft Windows Topics 22955@anchor{gnat_ugn/platform_specific_information id13}@anchor{1cb}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1cc} 22956@subsection Mixed-Language Programming on Windows 22957 22958 22959Developing pure Ada applications on Windows is no different than on 22960other GNAT-supported platforms. However, when developing or porting an 22961application that contains a mix of Ada and C/C++, the choice of your 22962Windows C/C++ development environment conditions your overall 22963interoperability strategy. 22964 22965If you use @code{gcc} or Microsoft C to compile the non-Ada part of 22966your application, there are no Windows-specific restrictions that 22967affect the overall interoperability with your Ada code. If you do want 22968to use the Microsoft tools for your C++ code, you have two choices: 22969 22970 22971@itemize * 22972 22973@item 22974Encapsulate your C++ code in a DLL to be linked with your Ada 22975application. In this case, use the Microsoft or whatever environment to 22976build the DLL and use GNAT to build your executable 22977(@ref{1cd,,Using DLLs with GNAT}). 22978 22979@item 22980Or you can encapsulate your Ada code in a DLL to be linked with the 22981other part of your application. In this case, use GNAT to build the DLL 22982(@ref{1ce,,Building DLLs with GNAT Project files}) and use the Microsoft 22983or whatever environment to build your executable. 22984@end itemize 22985 22986In addition to the description about C main in 22987@ref{2c,,Mixed Language Programming} section, if the C main uses a 22988stand-alone library it is required on x86-windows to 22989setup the SEH context. For this the C main must looks like this: 22990 22991@quotation 22992 22993@example 22994/* main.c */ 22995extern void adainit (void); 22996extern void adafinal (void); 22997extern void __gnat_initialize(void*); 22998extern void call_to_ada (void); 22999 23000int main (int argc, char *argv[]) 23001@{ 23002 int SEH [2]; 23003 23004 /* Initialize the SEH context */ 23005 __gnat_initialize (&SEH); 23006 23007 adainit(); 23008 23009 /* Then call Ada services in the stand-alone library */ 23010 23011 call_to_ada(); 23012 23013 adafinal(); 23014@} 23015@end example 23016@end quotation 23017 23018Note that this is not needed on x86_64-windows where the Windows 23019native SEH support is used. 23020 23021@menu 23022* Windows Calling Conventions:: 23023* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. 23024* Using DLLs with GNAT:: 23025* Building DLLs with GNAT Project files:: 23026* Building DLLs with GNAT:: 23027* Building DLLs with gnatdll:: 23028* Ada DLLs and Finalization:: 23029* Creating a Spec for Ada DLLs:: 23030* GNAT and Windows Resources:: 23031* Using GNAT DLLs from Microsoft Visual Studio Applications:: 23032* Debugging a DLL:: 23033* Setting Stack Size from gnatlink:: 23034* Setting Heap Size from gnatlink:: 23035 23036@end menu 23037 23038@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows 23039@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1cf}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1d0} 23040@subsubsection Windows Calling Conventions 23041 23042 23043@geindex Stdcall 23044 23045@geindex APIENTRY 23046 23047This section pertain only to Win32. On Win64 there is a single native 23048calling convention. All convention specifiers are ignored on this 23049platform. 23050 23051When a subprogram @code{F} (caller) calls a subprogram @code{G} 23052(callee), there are several ways to push @code{G}'s parameters on the 23053stack and there are several possible scenarios to clean up the stack 23054upon @code{G}'s return. A calling convention is an agreed upon software 23055protocol whereby the responsibilities between the caller (@code{F}) and 23056the callee (@code{G}) are clearly defined. Several calling conventions 23057are available for Windows: 23058 23059 23060@itemize * 23061 23062@item 23063@code{C} (Microsoft defined) 23064 23065@item 23066@code{Stdcall} (Microsoft defined) 23067 23068@item 23069@code{Win32} (GNAT specific) 23070 23071@item 23072@code{DLL} (GNAT specific) 23073@end itemize 23074 23075@menu 23076* C Calling Convention:: 23077* Stdcall Calling Convention:: 23078* Win32 Calling Convention:: 23079* DLL Calling Convention:: 23080 23081@end menu 23082 23083@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions 23084@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1d2} 23085@subsubsection @code{C} Calling Convention 23086 23087 23088This is the default calling convention used when interfacing to C/C++ 23089routines compiled with either @code{gcc} or Microsoft Visual C++. 23090 23091In the @code{C} calling convention subprogram parameters are pushed on the 23092stack by the caller from right to left. The caller itself is in charge of 23093cleaning up the stack after the call. In addition, the name of a routine 23094with @code{C} calling convention is mangled by adding a leading underscore. 23095 23096The name to use on the Ada side when importing (or exporting) a routine 23097with @code{C} calling convention is the name of the routine. For 23098instance the C function: 23099 23100@quotation 23101 23102@example 23103int get_val (long); 23104@end example 23105@end quotation 23106 23107should be imported from Ada as follows: 23108 23109@quotation 23110 23111@example 23112function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; 23113pragma Import (C, Get_Val, External_Name => "get_val"); 23114@end example 23115@end quotation 23116 23117Note that in this particular case the @code{External_Name} parameter could 23118have been omitted since, when missing, this parameter is taken to be the 23119name of the Ada entity in lower case. When the @code{Link_Name} parameter 23120is missing, as in the above example, this parameter is set to be the 23121@code{External_Name} with a leading underscore. 23122 23123When importing a variable defined in C, you should always use the @code{C} 23124calling convention unless the object containing the variable is part of a 23125DLL (in which case you should use the @code{Stdcall} calling 23126convention, @ref{1d3,,Stdcall Calling Convention}). 23127 23128@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions 23129@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1d4} 23130@subsubsection @code{Stdcall} Calling Convention 23131 23132 23133This convention, which was the calling convention used for Pascal 23134programs, is used by Microsoft for all the routines in the Win32 API for 23135efficiency reasons. It must be used to import any routine for which this 23136convention was specified. 23137 23138In the @code{Stdcall} calling convention subprogram parameters are pushed 23139on the stack by the caller from right to left. The callee (and not the 23140caller) is in charge of cleaning the stack on routine exit. In addition, 23141the name of a routine with @code{Stdcall} calling convention is mangled by 23142adding a leading underscore (as for the @code{C} calling convention) and a 23143trailing @code{@@@emph{nn}}, where @code{nn} is the overall size (in 23144bytes) of the parameters passed to the routine. 23145 23146The name to use on the Ada side when importing a C routine with a 23147@code{Stdcall} calling convention is the name of the C routine. The leading 23148underscore and trailing @code{@@@emph{nn}} are added automatically by 23149the compiler. For instance the Win32 function: 23150 23151@quotation 23152 23153@example 23154APIENTRY int get_val (long); 23155@end example 23156@end quotation 23157 23158should be imported from Ada as follows: 23159 23160@quotation 23161 23162@example 23163function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; 23164pragma Import (Stdcall, Get_Val); 23165-- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4" 23166@end example 23167@end quotation 23168 23169As for the @code{C} calling convention, when the @code{External_Name} 23170parameter is missing, it is taken to be the name of the Ada entity in lower 23171case. If instead of writing the above import pragma you write: 23172 23173@quotation 23174 23175@example 23176function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; 23177pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); 23178@end example 23179@end quotation 23180 23181then the imported routine is @code{_retrieve_val@@4}. However, if instead 23182of specifying the @code{External_Name} parameter you specify the 23183@code{Link_Name} as in the following example: 23184 23185@quotation 23186 23187@example 23188function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; 23189pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); 23190@end example 23191@end quotation 23192 23193then the imported routine is @code{retrieve_val}, that is, there is no 23194decoration at all. No leading underscore and no Stdcall suffix 23195@code{@@@emph{nn}}. 23196 23197This is especially important as in some special cases a DLL's entry 23198point name lacks a trailing @code{@@@emph{nn}} while the exported 23199name generated for a call has it. 23200 23201It is also possible to import variables defined in a DLL by using an 23202import pragma for a variable. As an example, if a DLL contains a 23203variable defined as: 23204 23205@quotation 23206 23207@example 23208int my_var; 23209@end example 23210@end quotation 23211 23212then, to access this variable from Ada you should write: 23213 23214@quotation 23215 23216@example 23217My_Var : Interfaces.C.int; 23218pragma Import (Stdcall, My_Var); 23219@end example 23220@end quotation 23221 23222Note that to ease building cross-platform bindings this convention 23223will be handled as a @code{C} calling convention on non-Windows platforms. 23224 23225@node Win32 Calling Convention,DLL Calling Convention,Stdcall Calling Convention,Windows Calling Conventions 23226@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1d5}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6} 23227@subsubsection @code{Win32} Calling Convention 23228 23229 23230This convention, which is GNAT-specific is fully equivalent to the 23231@code{Stdcall} calling convention described above. 23232 23233@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions 23234@anchor{gnat_ugn/platform_specific_information id18}@anchor{1d7}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1d8} 23235@subsubsection @code{DLL} Calling Convention 23236 23237 23238This convention, which is GNAT-specific is fully equivalent to the 23239@code{Stdcall} calling convention described above. 23240 23241@node Introduction to Dynamic Link Libraries DLLs,Using DLLs with GNAT,Windows Calling Conventions,Mixed-Language Programming on Windows 23242@anchor{gnat_ugn/platform_specific_information id19}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1da} 23243@subsubsection Introduction to Dynamic Link Libraries (DLLs) 23244 23245 23246@geindex DLL 23247 23248A Dynamically Linked Library (DLL) is a library that can be shared by 23249several applications running under Windows. A DLL can contain any number of 23250routines and variables. 23251 23252One advantage of DLLs is that you can change and enhance them without 23253forcing all the applications that depend on them to be relinked or 23254recompiled. However, you should be aware than all calls to DLL routines are 23255slower since, as you will understand below, such calls are indirect. 23256 23257To illustrate the remainder of this section, suppose that an application 23258wants to use the services of a DLL @code{API.dll}. To use the services 23259provided by @code{API.dll} you must statically link against the DLL or 23260an import library which contains a jump table with an entry for each 23261routine and variable exported by the DLL. In the Microsoft world this 23262import library is called @code{API.lib}. When using GNAT this import 23263library is called either @code{libAPI.dll.a}, @code{libapi.dll.a}, 23264@code{libAPI.a} or @code{libapi.a} (names are case insensitive). 23265 23266After you have linked your application with the DLL or the import library 23267and you run your application, here is what happens: 23268 23269 23270@itemize * 23271 23272@item 23273Your application is loaded into memory. 23274 23275@item 23276The DLL @code{API.dll} is mapped into the address space of your 23277application. This means that: 23278 23279 23280@itemize - 23281 23282@item 23283The DLL will use the stack of the calling thread. 23284 23285@item 23286The DLL will use the virtual address space of the calling process. 23287 23288@item 23289The DLL will allocate memory from the virtual address space of the calling 23290process. 23291 23292@item 23293Handles (pointers) can be safely exchanged between routines in the DLL 23294routines and routines in the application using the DLL. 23295@end itemize 23296 23297@item 23298The entries in the jump table (from the import library @code{libAPI.dll.a} 23299or @code{API.lib} or automatically created when linking against a DLL) 23300which is part of your application are initialized with the addresses 23301of the routines and variables in @code{API.dll}. 23302 23303@item 23304If present in @code{API.dll}, routines @code{DllMain} or 23305@code{DllMainCRTStartup} are invoked. These routines typically contain 23306the initialization code needed for the well-being of the routines and 23307variables exported by the DLL. 23308@end itemize 23309 23310There is an additional point which is worth mentioning. In the Windows 23311world there are two kind of DLLs: relocatable and non-relocatable 23312DLLs. Non-relocatable DLLs can only be loaded at a very specific address 23313in the target application address space. If the addresses of two 23314non-relocatable DLLs overlap and these happen to be used by the same 23315application, a conflict will occur and the application will run 23316incorrectly. Hence, when possible, it is always preferable to use and 23317build relocatable DLLs. Both relocatable and non-relocatable DLLs are 23318supported by GNAT. Note that the @code{-s} linker option (see GNU Linker 23319User's Guide) removes the debugging symbols from the DLL but the DLL can 23320still be relocated. 23321 23322As a side note, an interesting difference between Microsoft DLLs and 23323Unix shared libraries, is the fact that on most Unix systems all public 23324routines are exported by default in a Unix shared library, while under 23325Windows it is possible (but not required) to list exported routines in 23326a definition file (see @ref{1db,,The Definition File}). 23327 23328@node Using DLLs with GNAT,Building DLLs with GNAT Project files,Introduction to Dynamic Link Libraries DLLs,Mixed-Language Programming on Windows 23329@anchor{gnat_ugn/platform_specific_information id20}@anchor{1dc}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cd} 23330@subsubsection Using DLLs with GNAT 23331 23332 23333To use the services of a DLL, say @code{API.dll}, in your Ada application 23334you must have: 23335 23336 23337@itemize * 23338 23339@item 23340The Ada spec for the routines and/or variables you want to access in 23341@code{API.dll}. If not available this Ada spec must be built from the C/C++ 23342header files provided with the DLL. 23343 23344@item 23345The import library (@code{libAPI.dll.a} or @code{API.lib}). As previously 23346mentioned an import library is a statically linked library containing the 23347import table which will be filled at load time to point to the actual 23348@code{API.dll} routines. Sometimes you don't have an import library for the 23349DLL you want to use. The following sections will explain how to build 23350one. Note that this is optional. 23351 23352@item 23353The actual DLL, @code{API.dll}. 23354@end itemize 23355 23356Once you have all the above, to compile an Ada application that uses the 23357services of @code{API.dll} and whose main subprogram is @code{My_Ada_App}, 23358you simply issue the command 23359 23360@quotation 23361 23362@example 23363$ gnatmake my_ada_app -largs -lAPI 23364@end example 23365@end quotation 23366 23367The argument @code{-largs -lAPI} at the end of the @code{gnatmake} command 23368tells the GNAT linker to look for an import library. The linker will 23369look for a library name in this specific order: 23370 23371 23372@itemize * 23373 23374@item 23375@code{libAPI.dll.a} 23376 23377@item 23378@code{API.dll.a} 23379 23380@item 23381@code{libAPI.a} 23382 23383@item 23384@code{API.lib} 23385 23386@item 23387@code{libAPI.dll} 23388 23389@item 23390@code{API.dll} 23391@end itemize 23392 23393The first three are the GNU style import libraries. The third is the 23394Microsoft style import libraries. The last two are the actual DLL names. 23395 23396Note that if the Ada package spec for @code{API.dll} contains the 23397following pragma 23398 23399@quotation 23400 23401@example 23402pragma Linker_Options ("-lAPI"); 23403@end example 23404@end quotation 23405 23406you do not have to add @code{-largs -lAPI} at the end of the 23407@code{gnatmake} command. 23408 23409If any one of the items above is missing you will have to create it 23410yourself. The following sections explain how to do so using as an 23411example a fictitious DLL called @code{API.dll}. 23412 23413@menu 23414* Creating an Ada Spec for the DLL Services:: 23415* Creating an Import Library:: 23416 23417@end menu 23418 23419@node Creating an Ada Spec for the DLL Services,Creating an Import Library,,Using DLLs with GNAT 23420@anchor{gnat_ugn/platform_specific_information id21}@anchor{1dd}@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1de} 23421@subsubsection Creating an Ada Spec for the DLL Services 23422 23423 23424A DLL typically comes with a C/C++ header file which provides the 23425definitions of the routines and variables exported by the DLL. The Ada 23426equivalent of this header file is a package spec that contains definitions 23427for the imported entities. If the DLL you intend to use does not come with 23428an Ada spec you have to generate one such spec yourself. For example if 23429the header file of @code{API.dll} is a file @code{api.h} containing the 23430following two definitions: 23431 23432@quotation 23433 23434@example 23435int some_var; 23436int get (char *); 23437@end example 23438@end quotation 23439 23440then the equivalent Ada spec could be: 23441 23442@quotation 23443 23444@example 23445with Interfaces.C.Strings; 23446package API is 23447 use Interfaces; 23448 23449 Some_Var : C.int; 23450 function Get (Str : C.Strings.Chars_Ptr) return C.int; 23451 23452private 23453 pragma Import (C, Get); 23454 pragma Import (DLL, Some_Var); 23455end API; 23456@end example 23457@end quotation 23458 23459@node Creating an Import Library,,Creating an Ada Spec for the DLL Services,Using DLLs with GNAT 23460@anchor{gnat_ugn/platform_specific_information id22}@anchor{1df}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1e0} 23461@subsubsection Creating an Import Library 23462 23463 23464@geindex Import library 23465 23466If a Microsoft-style import library @code{API.lib} or a GNAT-style 23467import library @code{libAPI.dll.a} or @code{libAPI.a} is available 23468with @code{API.dll} you can skip this section. You can also skip this 23469section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools 23470as in this case it is possible to link directly against the 23471DLL. Otherwise read on. 23472 23473@geindex Definition file 23474@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1db} 23475@subsubheading The Definition File 23476 23477 23478As previously mentioned, and unlike Unix systems, the list of symbols 23479that are exported from a DLL must be provided explicitly in Windows. 23480The main goal of a definition file is precisely that: list the symbols 23481exported by a DLL. A definition file (usually a file with a @code{.def} 23482suffix) has the following structure: 23483 23484@quotation 23485 23486@example 23487[LIBRARY `@w{`}name`@w{`}] 23488[DESCRIPTION `@w{`}string`@w{`}] 23489EXPORTS 23490 `@w{`}symbol1`@w{`} 23491 `@w{`}symbol2`@w{`} 23492 ... 23493@end example 23494@end quotation 23495 23496 23497@table @asis 23498 23499@item @emph{LIBRARY name} 23500 23501This section, which is optional, gives the name of the DLL. 23502 23503@item @emph{DESCRIPTION string} 23504 23505This section, which is optional, gives a description string that will be 23506embedded in the import library. 23507 23508@item @emph{EXPORTS} 23509 23510This section gives the list of exported symbols (procedures, functions or 23511variables). For instance in the case of @code{API.dll} the @code{EXPORTS} 23512section of @code{API.def} looks like: 23513 23514@example 23515EXPORTS 23516 some_var 23517 get 23518@end example 23519@end table 23520 23521Note that you must specify the correct suffix (@code{@@@emph{nn}}) 23522(see @ref{1cf,,Windows Calling Conventions}) for a Stdcall 23523calling convention function in the exported symbols list. 23524 23525There can actually be other sections in a definition file, but these 23526sections are not relevant to the discussion at hand. 23527@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1e1} 23528@subsubheading Creating a Definition File Automatically 23529 23530 23531You can automatically create the definition file @code{API.def} 23532(see @ref{1db,,The Definition File}) from a DLL. 23533For that use the @code{dlltool} program as follows: 23534 23535@quotation 23536 23537@example 23538$ dlltool API.dll -z API.def --export-all-symbols 23539@end example 23540 23541Note that if some routines in the DLL have the @code{Stdcall} convention 23542(@ref{1cf,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}} 23543suffix then you'll have to edit @code{api.def} to add it, and specify 23544@code{-k} to @code{gnatdll} when creating the import library. 23545 23546Here are some hints to find the right @code{@@@emph{nn}} suffix. 23547 23548 23549@itemize - 23550 23551@item 23552If you have the Microsoft import library (.lib), it is possible to get 23553the right symbols by using Microsoft @code{dumpbin} tool (see the 23554corresponding Microsoft documentation for further details). 23555 23556@example 23557$ dumpbin /exports api.lib 23558@end example 23559 23560@item 23561If you have a message about a missing symbol at link time the compiler 23562tells you what symbol is expected. You just have to go back to the 23563definition file and add the right suffix. 23564@end itemize 23565@end quotation 23566@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e2} 23567@subsubheading GNAT-Style Import Library 23568 23569 23570To create a static import library from @code{API.dll} with the GNAT tools 23571you should create the .def file, then use @code{gnatdll} tool 23572(see @ref{1e3,,Using gnatdll}) as follows: 23573 23574@quotation 23575 23576@example 23577$ gnatdll -e API.def -d API.dll 23578@end example 23579 23580@code{gnatdll} takes as input a definition file @code{API.def} and the 23581name of the DLL containing the services listed in the definition file 23582@code{API.dll}. The name of the static import library generated is 23583computed from the name of the definition file as follows: if the 23584definition file name is @code{xyz.def}, the import library name will 23585be @code{libxyz.a}. Note that in the previous example option 23586@code{-e} could have been removed because the name of the definition 23587file (before the @code{.def} suffix) is the same as the name of the 23588DLL (@ref{1e3,,Using gnatdll} for more information about @code{gnatdll}). 23589@end quotation 23590@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e4} 23591@subsubheading Microsoft-Style Import Library 23592 23593 23594A Microsoft import library is needed only if you plan to make an 23595Ada DLL available to applications developed with Microsoft 23596tools (@ref{1cc,,Mixed-Language Programming on Windows}). 23597 23598To create a Microsoft-style import library for @code{API.dll} you 23599should create the .def file, then build the actual import library using 23600Microsoft's @code{lib} utility: 23601 23602@quotation 23603 23604@example 23605$ lib -machine:IX86 -def:API.def -out:API.lib 23606@end example 23607 23608If you use the above command the definition file @code{API.def} must 23609contain a line giving the name of the DLL: 23610 23611@example 23612LIBRARY "API" 23613@end example 23614 23615See the Microsoft documentation for further details about the usage of 23616@code{lib}. 23617@end quotation 23618 23619@node Building DLLs with GNAT Project files,Building DLLs with GNAT,Using DLLs with GNAT,Mixed-Language Programming on Windows 23620@anchor{gnat_ugn/platform_specific_information id23}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1ce} 23621@subsubsection Building DLLs with GNAT Project files 23622 23623 23624@geindex DLLs 23625@geindex building 23626 23627There is nothing specific to Windows in the build process. 23628See the @emph{Library Projects} section in the @emph{GNAT Project Manager} 23629chapter of the @emph{GPRbuild User's Guide}. 23630 23631Due to a system limitation, it is not possible under Windows to create threads 23632when inside the @code{DllMain} routine which is used for auto-initialization 23633of shared libraries, so it is not possible to have library level tasks in SALs. 23634 23635@node Building DLLs with GNAT,Building DLLs with gnatdll,Building DLLs with GNAT Project files,Mixed-Language Programming on Windows 23636@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{1e6}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7} 23637@subsubsection Building DLLs with GNAT 23638 23639 23640@geindex DLLs 23641@geindex building 23642 23643This section explain how to build DLLs using the GNAT built-in DLL 23644support. With the following procedure it is straight forward to build 23645and use DLLs with GNAT. 23646 23647 23648@itemize * 23649 23650@item 23651Building object files. 23652The first step is to build all objects files that are to be included 23653into the DLL. This is done by using the standard @code{gnatmake} tool. 23654 23655@item 23656Building the DLL. 23657To build the DLL you must use the @code{gcc} @code{-shared} and 23658@code{-shared-libgcc} options. It is quite simple to use this method: 23659 23660@example 23661$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ... 23662@end example 23663 23664It is important to note that in this case all symbols found in the 23665object files are automatically exported. It is possible to restrict 23666the set of symbols to export by passing to @code{gcc} a definition 23667file (see @ref{1db,,The Definition File}). 23668For example: 23669 23670@example 23671$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ... 23672@end example 23673 23674If you use a definition file you must export the elaboration procedures 23675for every package that required one. Elaboration procedures are named 23676using the package name followed by "_E". 23677 23678@item 23679Preparing DLL to be used. 23680For the DLL to be used by client programs the bodies must be hidden 23681from it and the .ali set with read-only attribute. This is very important 23682otherwise GNAT will recompile all packages and will not actually use 23683the code in the DLL. For example: 23684 23685@example 23686$ mkdir apilib 23687$ copy *.ads *.ali api.dll apilib 23688$ attrib +R apilib\\*.ali 23689@end example 23690@end itemize 23691 23692At this point it is possible to use the DLL by directly linking 23693against it. Note that you must use the GNAT shared runtime when using 23694GNAT shared libraries. This is achieved by using the @code{-shared} binder 23695option. 23696 23697@quotation 23698 23699@example 23700$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI 23701@end example 23702@end quotation 23703 23704@node Building DLLs with gnatdll,Ada DLLs and Finalization,Building DLLs with GNAT,Mixed-Language Programming on Windows 23705@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9} 23706@subsubsection Building DLLs with gnatdll 23707 23708 23709@geindex DLLs 23710@geindex building 23711 23712Note that it is preferred to use GNAT Project files 23713(@ref{1ce,,Building DLLs with GNAT Project files}) or the built-in GNAT 23714DLL support (@ref{1e6,,Building DLLs with GNAT}) or to build DLLs. 23715 23716This section explains how to build DLLs containing Ada code using 23717@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the 23718remainder of this section. 23719 23720The steps required to build an Ada DLL that is to be used by Ada as well as 23721non-Ada applications are as follows: 23722 23723 23724@itemize * 23725 23726@item 23727You need to mark each Ada entity exported by the DLL with a @code{C} or 23728@code{Stdcall} calling convention to avoid any Ada name mangling for the 23729entities exported by the DLL 23730(see @ref{1ea,,Exporting Ada Entities}). You can 23731skip this step if you plan to use the Ada DLL only from Ada applications. 23732 23733@item 23734Your Ada code must export an initialization routine which calls the routine 23735@code{adainit} generated by @code{gnatbind} to perform the elaboration of 23736the Ada code in the DLL (@ref{1eb,,Ada DLLs and Elaboration}). The initialization 23737routine exported by the Ada DLL must be invoked by the clients of the DLL 23738to initialize the DLL. 23739 23740@item 23741When useful, the DLL should also export a finalization routine which calls 23742routine @code{adafinal} generated by @code{gnatbind} to perform the 23743finalization of the Ada code in the DLL (@ref{1ec,,Ada DLLs and Finalization}). 23744The finalization routine exported by the Ada DLL must be invoked by the 23745clients of the DLL when the DLL services are no further needed. 23746 23747@item 23748You must provide a spec for the services exported by the Ada DLL in each 23749of the programming languages to which you plan to make the DLL available. 23750 23751@item 23752You must provide a definition file listing the exported entities 23753(@ref{1db,,The Definition File}). 23754 23755@item 23756Finally you must use @code{gnatdll} to produce the DLL and the import 23757library (@ref{1e3,,Using gnatdll}). 23758@end itemize 23759 23760Note that a relocatable DLL stripped using the @code{strip} 23761binutils tool will not be relocatable anymore. To build a DLL without 23762debug information pass @code{-largs -s} to @code{gnatdll}. This 23763restriction does not apply to a DLL built using a Library Project. 23764See the @emph{Library Projects} section in the @emph{GNAT Project Manager} 23765chapter of the @emph{GPRbuild User's Guide}. 23766 23767@c Limitations_When_Using_Ada_DLLs_from Ada: 23768 23769@menu 23770* Limitations When Using Ada DLLs from Ada:: 23771* Exporting Ada Entities:: 23772* Ada DLLs and Elaboration:: 23773 23774@end menu 23775 23776@node Limitations When Using Ada DLLs from Ada,Exporting Ada Entities,,Building DLLs with gnatdll 23777@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{1ed} 23778@subsubsection Limitations When Using Ada DLLs from Ada 23779 23780 23781When using Ada DLLs from Ada applications there is a limitation users 23782should be aware of. Because on Windows the GNAT run-time is not in a DLL of 23783its own, each Ada DLL includes a part of the GNAT run-time. Specifically, 23784each Ada DLL includes the services of the GNAT run-time that are necessary 23785to the Ada code inside the DLL. As a result, when an Ada program uses an 23786Ada DLL there are two independent GNAT run-times: one in the Ada DLL and 23787one in the main program. 23788 23789It is therefore not possible to exchange GNAT run-time objects between the 23790Ada DLL and the main Ada program. Example of GNAT run-time objects are file 23791handles (e.g., @code{Text_IO.File_Type}), tasks types, protected objects 23792types, etc. 23793 23794It is completely safe to exchange plain elementary, array or record types, 23795Windows object handles, etc. 23796 23797@node Exporting Ada Entities,Ada DLLs and Elaboration,Limitations When Using Ada DLLs from Ada,Building DLLs with gnatdll 23798@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1ee} 23799@subsubsection Exporting Ada Entities 23800 23801 23802@geindex Export table 23803 23804Building a DLL is a way to encapsulate a set of services usable from any 23805application. As a result, the Ada entities exported by a DLL should be 23806exported with the @code{C} or @code{Stdcall} calling conventions to avoid 23807any Ada name mangling. As an example here is an Ada package 23808@code{API}, spec and body, exporting two procedures, a function, and a 23809variable: 23810 23811@quotation 23812 23813@example 23814with Interfaces.C; use Interfaces; 23815package API is 23816 Count : C.int := 0; 23817 function Factorial (Val : C.int) return C.int; 23818 23819 procedure Initialize_API; 23820 procedure Finalize_API; 23821 -- Initialization & Finalization routines. More in the next section. 23822private 23823 pragma Export (C, Initialize_API); 23824 pragma Export (C, Finalize_API); 23825 pragma Export (C, Count); 23826 pragma Export (C, Factorial); 23827end API; 23828@end example 23829 23830@example 23831package body API is 23832 function Factorial (Val : C.int) return C.int is 23833 Fact : C.int := 1; 23834 begin 23835 Count := Count + 1; 23836 for K in 1 .. Val loop 23837 Fact := Fact * K; 23838 end loop; 23839 return Fact; 23840 end Factorial; 23841 23842 procedure Initialize_API is 23843 procedure Adainit; 23844 pragma Import (C, Adainit); 23845 begin 23846 Adainit; 23847 end Initialize_API; 23848 23849 procedure Finalize_API is 23850 procedure Adafinal; 23851 pragma Import (C, Adafinal); 23852 begin 23853 Adafinal; 23854 end Finalize_API; 23855end API; 23856@end example 23857@end quotation 23858 23859If the Ada DLL you are building will only be used by Ada applications 23860you do not have to export Ada entities with a @code{C} or @code{Stdcall} 23861convention. As an example, the previous package could be written as 23862follows: 23863 23864@quotation 23865 23866@example 23867package API is 23868 Count : Integer := 0; 23869 function Factorial (Val : Integer) return Integer; 23870 23871 procedure Initialize_API; 23872 procedure Finalize_API; 23873 -- Initialization and Finalization routines. 23874end API; 23875@end example 23876 23877@example 23878package body API is 23879 function Factorial (Val : Integer) return Integer is 23880 Fact : Integer := 1; 23881 begin 23882 Count := Count + 1; 23883 for K in 1 .. Val loop 23884 Fact := Fact * K; 23885 end loop; 23886 return Fact; 23887 end Factorial; 23888 23889 ... 23890 -- The remainder of this package body is unchanged. 23891end API; 23892@end example 23893@end quotation 23894 23895Note that if you do not export the Ada entities with a @code{C} or 23896@code{Stdcall} convention you will have to provide the mangled Ada names 23897in the definition file of the Ada DLL 23898(@ref{1ef,,Creating the Definition File}). 23899 23900@node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll 23901@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{1eb}@anchor{gnat_ugn/platform_specific_information id27}@anchor{1f0} 23902@subsubsection Ada DLLs and Elaboration 23903 23904 23905@geindex DLLs and elaboration 23906 23907The DLL that you are building contains your Ada code as well as all the 23908routines in the Ada library that are needed by it. The first thing a 23909user of your DLL must do is elaborate the Ada code 23910(@ref{f,,Elaboration Order Handling in GNAT}). 23911 23912To achieve this you must export an initialization routine 23913(@code{Initialize_API} in the previous example), which must be invoked 23914before using any of the DLL services. This elaboration routine must call 23915the Ada elaboration routine @code{adainit} generated by the GNAT binder 23916(@ref{a0,,Binding with Non-Ada Main Programs}). See the body of 23917@code{Initialize_Api} for an example. Note that the GNAT binder is 23918automatically invoked during the DLL build process by the @code{gnatdll} 23919tool (@ref{1e3,,Using gnatdll}). 23920 23921When a DLL is loaded, Windows systematically invokes a routine called 23922@code{DllMain}. It would therefore be possible to call @code{adainit} 23923directly from @code{DllMain} without having to provide an explicit 23924initialization routine. Unfortunately, it is not possible to call 23925@code{adainit} from the @code{DllMain} if your program has library level 23926tasks because access to the @code{DllMain} entry point is serialized by 23927the system (that is, only a single thread can execute 'through' it at a 23928time), which means that the GNAT run-time will deadlock waiting for the 23929newly created task to complete its initialization. 23930 23931@node Ada DLLs and Finalization,Creating a Spec for Ada DLLs,Building DLLs with gnatdll,Mixed-Language Programming on Windows 23932@anchor{gnat_ugn/platform_specific_information id28}@anchor{1f1}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{1ec} 23933@subsubsection Ada DLLs and Finalization 23934 23935 23936@geindex DLLs and finalization 23937 23938When the services of an Ada DLL are no longer needed, the client code should 23939invoke the DLL finalization routine, if available. The DLL finalization 23940routine is in charge of releasing all resources acquired by the DLL. In the 23941case of the Ada code contained in the DLL, this is achieved by calling 23942routine @code{adafinal} generated by the GNAT binder 23943(@ref{a0,,Binding with Non-Ada Main Programs}). 23944See the body of @code{Finalize_Api} for an 23945example. As already pointed out the GNAT binder is automatically invoked 23946during the DLL build process by the @code{gnatdll} tool 23947(@ref{1e3,,Using gnatdll}). 23948 23949@node Creating a Spec for Ada DLLs,GNAT and Windows Resources,Ada DLLs and Finalization,Mixed-Language Programming on Windows 23950@anchor{gnat_ugn/platform_specific_information id29}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{1f3} 23951@subsubsection Creating a Spec for Ada DLLs 23952 23953 23954To use the services exported by the Ada DLL from another programming 23955language (e.g., C), you have to translate the specs of the exported Ada 23956entities in that language. For instance in the case of @code{API.dll}, 23957the corresponding C header file could look like: 23958 23959@quotation 23960 23961@example 23962extern int *_imp__count; 23963#define count (*_imp__count) 23964int factorial (int); 23965@end example 23966@end quotation 23967 23968It is important to understand that when building an Ada DLL to be used by 23969other Ada applications, you need two different specs for the packages 23970contained in the DLL: one for building the DLL and the other for using 23971the DLL. This is because the @code{DLL} calling convention is needed to 23972use a variable defined in a DLL, but when building the DLL, the variable 23973must have either the @code{Ada} or @code{C} calling convention. As an 23974example consider a DLL comprising the following package @code{API}: 23975 23976@quotation 23977 23978@example 23979package API is 23980 Count : Integer := 0; 23981 ... 23982 -- Remainder of the package omitted. 23983end API; 23984@end example 23985@end quotation 23986 23987After producing a DLL containing package @code{API}, the spec that 23988must be used to import @code{API.Count} from Ada code outside of the 23989DLL is: 23990 23991@quotation 23992 23993@example 23994package API is 23995 Count : Integer; 23996 pragma Import (DLL, Count); 23997end API; 23998@end example 23999@end quotation 24000 24001@menu 24002* Creating the Definition File:: 24003* Using gnatdll:: 24004 24005@end menu 24006 24007@node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs 24008@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{1ef}@anchor{gnat_ugn/platform_specific_information id30}@anchor{1f4} 24009@subsubsection Creating the Definition File 24010 24011 24012The definition file is the last file needed to build the DLL. It lists 24013the exported symbols. As an example, the definition file for a DLL 24014containing only package @code{API} (where all the entities are exported 24015with a @code{C} calling convention) is: 24016 24017@quotation 24018 24019@example 24020EXPORTS 24021 count 24022 factorial 24023 finalize_api 24024 initialize_api 24025@end example 24026@end quotation 24027 24028If the @code{C} calling convention is missing from package @code{API}, 24029then the definition file contains the mangled Ada names of the above 24030entities, which in this case are: 24031 24032@quotation 24033 24034@example 24035EXPORTS 24036 api__count 24037 api__factorial 24038 api__finalize_api 24039 api__initialize_api 24040@end example 24041@end quotation 24042 24043@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs 24044@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f5} 24045@subsubsection Using @code{gnatdll} 24046 24047 24048@geindex gnatdll 24049 24050@code{gnatdll} is a tool to automate the DLL build process once all the Ada 24051and non-Ada sources that make up your DLL have been compiled. 24052@code{gnatdll} is actually in charge of two distinct tasks: build the 24053static import library for the DLL and the actual DLL. The form of the 24054@code{gnatdll} command is 24055 24056@quotation 24057 24058@example 24059$ gnatdll [ switches ] list-of-files [ -largs opts ] 24060@end example 24061@end quotation 24062 24063where @code{list-of-files} is a list of ALI and object files. The object 24064file list must be the exact list of objects corresponding to the non-Ada 24065sources whose services are to be included in the DLL. The ALI file list 24066must be the exact list of ALI files for the corresponding Ada sources 24067whose services are to be included in the DLL. If @code{list-of-files} is 24068missing, only the static import library is generated. 24069 24070You may specify any of the following switches to @code{gnatdll}: 24071 24072@quotation 24073 24074@geindex -a (gnatdll) 24075@end quotation 24076 24077 24078@table @asis 24079 24080@item @code{-a[@emph{address}]} 24081 24082Build a non-relocatable DLL at @code{address}. If @code{address} is not 24083specified the default address @code{0x11000000} will be used. By default, 24084when this switch is missing, @code{gnatdll} builds relocatable DLL. We 24085advise the reader to build relocatable DLL. 24086 24087@geindex -b (gnatdll) 24088 24089@item @code{-b @emph{address}} 24090 24091Set the relocatable DLL base address. By default the address is 24092@code{0x11000000}. 24093 24094@geindex -bargs (gnatdll) 24095 24096@item @code{-bargs @emph{opts}} 24097 24098Binder options. Pass @code{opts} to the binder. 24099 24100@geindex -d (gnatdll) 24101 24102@item @code{-d @emph{dllfile}} 24103 24104@code{dllfile} is the name of the DLL. This switch must be present for 24105@code{gnatdll} to do anything. The name of the generated import library is 24106obtained algorithmically from @code{dllfile} as shown in the following 24107example: if @code{dllfile} is @code{xyz.dll}, the import library name is 24108@code{libxyz.dll.a}. The name of the definition file to use (if not specified 24109by option @code{-e}) is obtained algorithmically from @code{dllfile} 24110as shown in the following example: 24111if @code{dllfile} is @code{xyz.dll}, the definition 24112file used is @code{xyz.def}. 24113 24114@geindex -e (gnatdll) 24115 24116@item @code{-e @emph{deffile}} 24117 24118@code{deffile} is the name of the definition file. 24119 24120@geindex -g (gnatdll) 24121 24122@item @code{-g} 24123 24124Generate debugging information. This information is stored in the object 24125file and copied from there to the final DLL file by the linker, 24126where it can be read by the debugger. You must use the 24127@code{-g} switch if you plan on using the debugger or the symbolic 24128stack traceback. 24129 24130@geindex -h (gnatdll) 24131 24132@item @code{-h} 24133 24134Help mode. Displays @code{gnatdll} switch usage information. 24135 24136@geindex -I (gnatdll) 24137 24138@item @code{-I@emph{dir}} 24139 24140Direct @code{gnatdll} to search the @code{dir} directory for source and 24141object files needed to build the DLL. 24142(@ref{73,,Search Paths and the Run-Time Library (RTL)}). 24143 24144@geindex -k (gnatdll) 24145 24146@item @code{-k} 24147 24148Removes the @code{@@@emph{nn}} suffix from the import library's exported 24149names, but keeps them for the link names. You must specify this 24150option if you want to use a @code{Stdcall} function in a DLL for which 24151the @code{@@@emph{nn}} suffix has been removed. This is the case for most 24152of the Windows NT DLL for example. This option has no effect when 24153@code{-n} option is specified. 24154 24155@geindex -l (gnatdll) 24156 24157@item @code{-l @emph{file}} 24158 24159The list of ALI and object files used to build the DLL are listed in 24160@code{file}, instead of being given in the command line. Each line in 24161@code{file} contains the name of an ALI or object file. 24162 24163@geindex -n (gnatdll) 24164 24165@item @code{-n} 24166 24167No Import. Do not create the import library. 24168 24169@geindex -q (gnatdll) 24170 24171@item @code{-q} 24172 24173Quiet mode. Do not display unnecessary messages. 24174 24175@geindex -v (gnatdll) 24176 24177@item @code{-v} 24178 24179Verbose mode. Display extra information. 24180 24181@geindex -largs (gnatdll) 24182 24183@item @code{-largs @emph{opts}} 24184 24185Linker options. Pass @code{opts} to the linker. 24186@end table 24187 24188@subsubheading @code{gnatdll} Example 24189 24190 24191As an example the command to build a relocatable DLL from @code{api.adb} 24192once @code{api.adb} has been compiled and @code{api.def} created is 24193 24194@quotation 24195 24196@example 24197$ gnatdll -d api.dll api.ali 24198@end example 24199@end quotation 24200 24201The above command creates two files: @code{libapi.dll.a} (the import 24202library) and @code{api.dll} (the actual DLL). If you want to create 24203only the DLL, just type: 24204 24205@quotation 24206 24207@example 24208$ gnatdll -d api.dll -n api.ali 24209@end example 24210@end quotation 24211 24212Alternatively if you want to create just the import library, type: 24213 24214@quotation 24215 24216@example 24217$ gnatdll -d api.dll 24218@end example 24219@end quotation 24220 24221@subsubheading @code{gnatdll} behind the Scenes 24222 24223 24224This section details the steps involved in creating a DLL. @code{gnatdll} 24225does these steps for you. Unless you are interested in understanding what 24226goes on behind the scenes, you should skip this section. 24227 24228We use the previous example of a DLL containing the Ada package @code{API}, 24229to illustrate the steps necessary to build a DLL. The starting point is a 24230set of objects that will make up the DLL and the corresponding ALI 24231files. In the case of this example this means that @code{api.o} and 24232@code{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does 24233the following: 24234 24235 24236@itemize * 24237 24238@item 24239@code{gnatdll} builds the base file (@code{api.base}). A base file gives 24240the information necessary to generate relocation information for the 24241DLL. 24242 24243@example 24244$ gnatbind -n api 24245$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base 24246@end example 24247 24248In addition to the base file, the @code{gnatlink} command generates an 24249output file @code{api.jnk} which can be discarded. The @code{-mdll} switch 24250asks @code{gnatlink} to generate the routines @code{DllMain} and 24251@code{DllMainCRTStartup} that are called by the Windows loader when the DLL 24252is loaded into memory. 24253 24254@item 24255@code{gnatdll} uses @code{dlltool} (see @ref{1f6,,Using dlltool}) to build the 24256export table (@code{api.exp}). The export table contains the relocation 24257information in a form which can be used during the final link to ensure 24258that the Windows loader is able to place the DLL anywhere in memory. 24259 24260@example 24261$ dlltool --dllname api.dll --def api.def --base-file api.base \\ 24262 --output-exp api.exp 24263@end example 24264 24265@item 24266@code{gnatdll} builds the base file using the new export table. Note that 24267@code{gnatbind} must be called once again since the binder generated file 24268has been deleted during the previous call to @code{gnatlink}. 24269 24270@example 24271$ gnatbind -n api 24272$ gnatlink api -o api.jnk api.exp -mdll 24273 -Wl,--base-file,api.base 24274@end example 24275 24276@item 24277@code{gnatdll} builds the new export table using the new base file and 24278generates the DLL import library @code{libAPI.dll.a}. 24279 24280@example 24281$ dlltool --dllname api.dll --def api.def --base-file api.base \\ 24282 --output-exp api.exp --output-lib libAPI.a 24283@end example 24284 24285@item 24286Finally @code{gnatdll} builds the relocatable DLL using the final export 24287table. 24288 24289@example 24290$ gnatbind -n api 24291$ gnatlink api api.exp -o api.dll -mdll 24292@end example 24293@end itemize 24294@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f6} 24295@subsubheading Using @code{dlltool} 24296 24297 24298@code{dlltool} is the low-level tool used by @code{gnatdll} to build 24299DLLs and static import libraries. This section summarizes the most 24300common @code{dlltool} switches. The form of the @code{dlltool} command 24301is 24302 24303@quotation 24304 24305@example 24306$ dlltool [`switches`] 24307@end example 24308@end quotation 24309 24310@code{dlltool} switches include: 24311 24312@geindex --base-file (dlltool) 24313 24314 24315@table @asis 24316 24317@item @code{--base-file @emph{basefile}} 24318 24319Read the base file @code{basefile} generated by the linker. This switch 24320is used to create a relocatable DLL. 24321@end table 24322 24323@geindex --def (dlltool) 24324 24325 24326@table @asis 24327 24328@item @code{--def @emph{deffile}} 24329 24330Read the definition file. 24331@end table 24332 24333@geindex --dllname (dlltool) 24334 24335 24336@table @asis 24337 24338@item @code{--dllname @emph{name}} 24339 24340Gives the name of the DLL. This switch is used to embed the name of the 24341DLL in the static import library generated by @code{dlltool} with switch 24342@code{--output-lib}. 24343@end table 24344 24345@geindex -k (dlltool) 24346 24347 24348@table @asis 24349 24350@item @code{-k} 24351 24352Kill @code{@@@emph{nn}} from exported names 24353(@ref{1cf,,Windows Calling Conventions} 24354for a discussion about @code{Stdcall}-style symbols. 24355@end table 24356 24357@geindex --help (dlltool) 24358 24359 24360@table @asis 24361 24362@item @code{--help} 24363 24364Prints the @code{dlltool} switches with a concise description. 24365@end table 24366 24367@geindex --output-exp (dlltool) 24368 24369 24370@table @asis 24371 24372@item @code{--output-exp @emph{exportfile}} 24373 24374Generate an export file @code{exportfile}. The export file contains the 24375export table (list of symbols in the DLL) and is used to create the DLL. 24376@end table 24377 24378@geindex --output-lib (dlltool) 24379 24380 24381@table @asis 24382 24383@item @code{--output-lib @emph{libfile}} 24384 24385Generate a static import library @code{libfile}. 24386@end table 24387 24388@geindex -v (dlltool) 24389 24390 24391@table @asis 24392 24393@item @code{-v} 24394 24395Verbose mode. 24396@end table 24397 24398@geindex --as (dlltool) 24399 24400 24401@table @asis 24402 24403@item @code{--as @emph{assembler-name}} 24404 24405Use @code{assembler-name} as the assembler. The default is @code{as}. 24406@end table 24407 24408@node GNAT and Windows Resources,Using GNAT DLLs from Microsoft Visual Studio Applications,Creating a Spec for Ada DLLs,Mixed-Language Programming on Windows 24409@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{1f7}@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f8} 24410@subsubsection GNAT and Windows Resources 24411 24412 24413@geindex Resources 24414@geindex windows 24415 24416Resources are an easy way to add Windows specific objects to your 24417application. The objects that can be added as resources include: 24418 24419 24420@itemize * 24421 24422@item 24423menus 24424 24425@item 24426accelerators 24427 24428@item 24429dialog boxes 24430 24431@item 24432string tables 24433 24434@item 24435bitmaps 24436 24437@item 24438cursors 24439 24440@item 24441icons 24442 24443@item 24444fonts 24445 24446@item 24447version information 24448@end itemize 24449 24450For example, a version information resource can be defined as follow and 24451embedded into an executable or DLL: 24452 24453A version information resource can be used to embed information into an 24454executable or a DLL. These information can be viewed using the file properties 24455from the Windows Explorer. Here is an example of a version information 24456resource: 24457 24458@quotation 24459 24460@example 244611 VERSIONINFO 24462FILEVERSION 1,0,0,0 24463PRODUCTVERSION 1,0,0,0 24464BEGIN 24465 BLOCK "StringFileInfo" 24466 BEGIN 24467 BLOCK "080904E4" 24468 BEGIN 24469 VALUE "CompanyName", "My Company Name" 24470 VALUE "FileDescription", "My application" 24471 VALUE "FileVersion", "1.0" 24472 VALUE "InternalName", "my_app" 24473 VALUE "LegalCopyright", "My Name" 24474 VALUE "OriginalFilename", "my_app.exe" 24475 VALUE "ProductName", "My App" 24476 VALUE "ProductVersion", "1.0" 24477 END 24478 END 24479 24480 BLOCK "VarFileInfo" 24481 BEGIN 24482 VALUE "Translation", 0x809, 1252 24483 END 24484END 24485@end example 24486@end quotation 24487 24488The value @code{0809} (langID) is for the U.K English language and 24489@code{04E4} (charsetID), which is equal to @code{1252} decimal, for 24490multilingual. 24491 24492This section explains how to build, compile and use resources. Note that this 24493section does not cover all resource objects, for a complete description see 24494the corresponding Microsoft documentation. 24495 24496@menu 24497* Building Resources:: 24498* Compiling Resources:: 24499* Using Resources:: 24500 24501@end menu 24502 24503@node Building Resources,Compiling Resources,,GNAT and Windows Resources 24504@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa} 24505@subsubsection Building Resources 24506 24507 24508@geindex Resources 24509@geindex building 24510 24511A resource file is an ASCII file. By convention resource files have an 24512@code{.rc} extension. 24513The easiest way to build a resource file is to use Microsoft tools 24514such as @code{imagedit.exe} to build bitmaps, icons and cursors and 24515@code{dlgedit.exe} to build dialogs. 24516It is always possible to build an @code{.rc} file yourself by writing a 24517resource script. 24518 24519It is not our objective to explain how to write a resource file. A 24520complete description of the resource script language can be found in the 24521Microsoft documentation. 24522 24523@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources 24524@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc} 24525@subsubsection Compiling Resources 24526 24527 24528@geindex rc 24529 24530@geindex windres 24531 24532@geindex Resources 24533@geindex compiling 24534 24535This section describes how to build a GNAT-compatible (COFF) object file 24536containing the resources. This is done using the Resource Compiler 24537@code{windres} as follows: 24538 24539@quotation 24540 24541@example 24542$ windres -i myres.rc -o myres.o 24543@end example 24544@end quotation 24545 24546By default @code{windres} will run @code{gcc} to preprocess the @code{.rc} 24547file. You can specify an alternate preprocessor (usually named 24548@code{cpp.exe}) using the @code{windres} @code{--preprocessor} 24549parameter. A list of all possible options may be obtained by entering 24550the command @code{windres} @code{--help}. 24551 24552It is also possible to use the Microsoft resource compiler @code{rc.exe} 24553to produce a @code{.res} file (binary resource file). See the 24554corresponding Microsoft documentation for further details. In this case 24555you need to use @code{windres} to translate the @code{.res} file to a 24556GNAT-compatible object file as follows: 24557 24558@quotation 24559 24560@example 24561$ windres -i myres.res -o myres.o 24562@end example 24563@end quotation 24564 24565@node Using Resources,,Compiling Resources,GNAT and Windows Resources 24566@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe} 24567@subsubsection Using Resources 24568 24569 24570@geindex Resources 24571@geindex using 24572 24573To include the resource file in your program just add the 24574GNAT-compatible object file for the resource(s) to the linker 24575arguments. With @code{gnatmake} this is done by using the @code{-largs} 24576option: 24577 24578@quotation 24579 24580@example 24581$ gnatmake myprog -largs myres.o 24582@end example 24583@end quotation 24584 24585@node Using GNAT DLLs from Microsoft Visual Studio Applications,Debugging a DLL,GNAT and Windows Resources,Mixed-Language Programming on Windows 24586@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{1ff}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{200} 24587@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications 24588 24589 24590@geindex Microsoft Visual Studio 24591@geindex use with GNAT DLLs 24592 24593This section describes a common case of mixed GNAT/Microsoft Visual Studio 24594application development, where the main program is developed using MSVS, and 24595is linked with a DLL developed using GNAT. Such a mixed application should 24596be developed following the general guidelines outlined above; below is the 24597cookbook-style sequence of steps to follow: 24598 24599 24600@enumerate 24601 24602@item 24603First develop and build the GNAT shared library using a library project 24604(let's assume the project is @code{mylib.gpr}, producing the library @code{libmylib.dll}): 24605@end enumerate 24606 24607@quotation 24608 24609@example 24610$ gprbuild -p mylib.gpr 24611@end example 24612@end quotation 24613 24614 24615@enumerate 2 24616 24617@item 24618Produce a .def file for the symbols you need to interface with, either by 24619hand or automatically with possibly some manual adjustments 24620(see @ref{1e1,,Creating Definition File Automatically}): 24621@end enumerate 24622 24623@quotation 24624 24625@example 24626$ dlltool libmylib.dll -z libmylib.def --export-all-symbols 24627@end example 24628@end quotation 24629 24630 24631@enumerate 3 24632 24633@item 24634Make sure that MSVS command-line tools are accessible on the path. 24635 24636@item 24637Create the Microsoft-style import library (see @ref{1e4,,MSVS-Style Import Library}): 24638@end enumerate 24639 24640@quotation 24641 24642@example 24643$ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib 24644@end example 24645@end quotation 24646 24647If you are using a 64-bit toolchain, the above becomes... 24648 24649@quotation 24650 24651@example 24652$ lib -machine:X64 -def:libmylib.def -out:libmylib.lib 24653@end example 24654@end quotation 24655 24656 24657@enumerate 5 24658 24659@item 24660Build the C main 24661@end enumerate 24662 24663@quotation 24664 24665@example 24666$ cl /O2 /MD main.c libmylib.lib 24667@end example 24668@end quotation 24669 24670 24671@enumerate 6 24672 24673@item 24674Before running the executable, make sure you have set the PATH to the DLL, 24675or copy the DLL into into the directory containing the .exe. 24676@end enumerate 24677 24678@node Debugging a DLL,Setting Stack Size from gnatlink,Using GNAT DLLs from Microsoft Visual Studio Applications,Mixed-Language Programming on Windows 24679@anchor{gnat_ugn/platform_specific_information id36}@anchor{201}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{202} 24680@subsubsection Debugging a DLL 24681 24682 24683@geindex DLL debugging 24684 24685Debugging a DLL is similar to debugging a standard program. But 24686we have to deal with two different executable parts: the DLL and the 24687program that uses it. We have the following four possibilities: 24688 24689 24690@itemize * 24691 24692@item 24693The program and the DLL are built with GCC/GNAT. 24694 24695@item 24696The program is built with foreign tools and the DLL is built with 24697GCC/GNAT. 24698 24699@item 24700The program is built with GCC/GNAT and the DLL is built with 24701foreign tools. 24702@end itemize 24703 24704In this section we address only cases one and two above. 24705There is no point in trying to debug 24706a DLL with GNU/GDB, if there is no GDB-compatible debugging 24707information in it. To do so you must use a debugger compatible with the 24708tools suite used to build the DLL. 24709 24710@menu 24711* Program and DLL Both Built with GCC/GNAT:: 24712* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: 24713 24714@end menu 24715 24716@node Program and DLL Both Built with GCC/GNAT,Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Debugging a DLL 24717@anchor{gnat_ugn/platform_specific_information id37}@anchor{203}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{204} 24718@subsubsection Program and DLL Both Built with GCC/GNAT 24719 24720 24721This is the simplest case. Both the DLL and the program have @code{GDB} 24722compatible debugging information. It is then possible to break anywhere in 24723the process. Let's suppose here that the main procedure is named 24724@code{ada_main} and that in the DLL there is an entry point named 24725@code{ada_dll}. 24726 24727The DLL (@ref{1da,,Introduction to Dynamic Link Libraries (DLLs)}) and 24728program must have been built with the debugging information (see GNAT -g 24729switch). Here are the step-by-step instructions for debugging it: 24730 24731 24732@itemize * 24733 24734@item 24735Launch @code{GDB} on the main program. 24736 24737@example 24738$ gdb -nw ada_main 24739@end example 24740 24741@item 24742Start the program and stop at the beginning of the main procedure 24743 24744@example 24745(gdb) start 24746@end example 24747 24748This step is required to be able to set a breakpoint inside the DLL. As long 24749as the program is not run, the DLL is not loaded. This has the 24750consequence that the DLL debugging information is also not loaded, so it is not 24751possible to set a breakpoint in the DLL. 24752 24753@item 24754Set a breakpoint inside the DLL 24755 24756@example 24757(gdb) break ada_dll 24758(gdb) cont 24759@end example 24760@end itemize 24761 24762At this stage a breakpoint is set inside the DLL. From there on 24763you can use the standard approach to debug the whole program 24764(@ref{14d,,Running and Debugging Ada Programs}). 24765 24766@node Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Program and DLL Both Built with GCC/GNAT,Debugging a DLL 24767@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{205}@anchor{gnat_ugn/platform_specific_information id38}@anchor{206} 24768@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT 24769 24770 24771In this case things are slightly more complex because it is not possible to 24772start the main program and then break at the beginning to load the DLL and the 24773associated DLL debugging information. It is not possible to break at the 24774beginning of the program because there is no @code{GDB} debugging information, 24775and therefore there is no direct way of getting initial control. This 24776section addresses this issue by describing some methods that can be used 24777to break somewhere in the DLL to debug it. 24778 24779First suppose that the main procedure is named @code{main} (this is for 24780example some C code built with Microsoft Visual C) and that there is a 24781DLL named @code{test.dll} containing an Ada entry point named 24782@code{ada_dll}. 24783 24784The DLL (see @ref{1da,,Introduction to Dynamic Link Libraries (DLLs)}) must have 24785been built with debugging information (see the GNAT @code{-g} option). 24786 24787@subsubheading Debugging the DLL Directly 24788 24789 24790 24791@itemize * 24792 24793@item 24794Find out the executable starting address 24795 24796@example 24797$ objdump --file-header main.exe 24798@end example 24799 24800The starting address is reported on the last line. For example: 24801 24802@example 24803main.exe: file format pei-i386 24804architecture: i386, flags 0x0000010a: 24805EXEC_P, HAS_DEBUG, D_PAGED 24806start address 0x00401010 24807@end example 24808 24809@item 24810Launch the debugger on the executable. 24811 24812@example 24813$ gdb main.exe 24814@end example 24815 24816@item 24817Set a breakpoint at the starting address, and launch the program. 24818 24819@example 24820$ (gdb) break *0x00401010 24821$ (gdb) run 24822@end example 24823 24824The program will stop at the given address. 24825 24826@item 24827Set a breakpoint on a DLL subroutine. 24828 24829@example 24830(gdb) break ada_dll.adb:45 24831@end example 24832 24833Or if you want to break using a symbol on the DLL, you need first to 24834select the Ada language (language used by the DLL). 24835 24836@example 24837(gdb) set language ada 24838(gdb) break ada_dll 24839@end example 24840 24841@item 24842Continue the program. 24843 24844@example 24845(gdb) cont 24846@end example 24847 24848This will run the program until it reaches the breakpoint that has been 24849set. From that point you can use the standard way to debug a program 24850as described in (@ref{14d,,Running and Debugging Ada Programs}). 24851@end itemize 24852 24853It is also possible to debug the DLL by attaching to a running process. 24854 24855@subsubheading Attaching to a Running Process 24856 24857 24858@geindex DLL debugging 24859@geindex attach to process 24860 24861With @code{GDB} it is always possible to debug a running process by 24862attaching to it. It is possible to debug a DLL this way. The limitation 24863of this approach is that the DLL must run long enough to perform the 24864attach operation. It may be useful for instance to insert a time wasting 24865loop in the code of the DLL to meet this criterion. 24866 24867 24868@itemize * 24869 24870@item 24871Launch the main program @code{main.exe}. 24872 24873@example 24874$ main 24875@end example 24876 24877@item 24878Use the Windows @emph{Task Manager} to find the process ID. Let's say 24879that the process PID for @code{main.exe} is 208. 24880 24881@item 24882Launch gdb. 24883 24884@example 24885$ gdb 24886@end example 24887 24888@item 24889Attach to the running process to be debugged. 24890 24891@example 24892(gdb) attach 208 24893@end example 24894 24895@item 24896Load the process debugging information. 24897 24898@example 24899(gdb) symbol-file main.exe 24900@end example 24901 24902@item 24903Break somewhere in the DLL. 24904 24905@example 24906(gdb) break ada_dll 24907@end example 24908 24909@item 24910Continue process execution. 24911 24912@example 24913(gdb) cont 24914@end example 24915@end itemize 24916 24917This last step will resume the process execution, and stop at 24918the breakpoint we have set. From there you can use the standard 24919approach to debug a program as described in 24920@ref{14d,,Running and Debugging Ada Programs}. 24921 24922@node Setting Stack Size from gnatlink,Setting Heap Size from gnatlink,Debugging a DLL,Mixed-Language Programming on Windows 24923@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127}@anchor{gnat_ugn/platform_specific_information id39}@anchor{207} 24924@subsubsection Setting Stack Size from @code{gnatlink} 24925 24926 24927It is possible to specify the program stack size at link time. On modern 24928versions of Windows, starting with XP, this is mostly useful to set the size of 24929the main stack (environment task). The other task stacks are set with pragma 24930Storage_Size or with the @emph{gnatbind -d} command. 24931 24932Since older versions of Windows (2000, NT4, etc.) do not allow setting the 24933reserve size of individual tasks, the link-time stack size applies to all 24934tasks, and pragma Storage_Size has no effect. 24935In particular, Stack Overflow checks are made against this 24936link-time specified size. 24937 24938This setting can be done with @code{gnatlink} using either of the following: 24939 24940 24941@itemize * 24942 24943@item 24944@code{-Xlinker} linker option 24945 24946@example 24947$ gnatlink hello -Xlinker --stack=0x10000,0x1000 24948@end example 24949 24950This sets the stack reserve size to 0x10000 bytes and the stack commit 24951size to 0x1000 bytes. 24952 24953@item 24954@code{-Wl} linker option 24955 24956@example 24957$ gnatlink hello -Wl,--stack=0x1000000 24958@end example 24959 24960This sets the stack reserve size to 0x1000000 bytes. Note that with 24961@code{-Wl} option it is not possible to set the stack commit size 24962because the comma is a separator for this option. 24963@end itemize 24964 24965@node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows 24966@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128}@anchor{gnat_ugn/platform_specific_information id40}@anchor{208} 24967@subsubsection Setting Heap Size from @code{gnatlink} 24968 24969 24970Under Windows systems, it is possible to specify the program heap size from 24971@code{gnatlink} using either of the following: 24972 24973 24974@itemize * 24975 24976@item 24977@code{-Xlinker} linker option 24978 24979@example 24980$ gnatlink hello -Xlinker --heap=0x10000,0x1000 24981@end example 24982 24983This sets the heap reserve size to 0x10000 bytes and the heap commit 24984size to 0x1000 bytes. 24985 24986@item 24987@code{-Wl} linker option 24988 24989@example 24990$ gnatlink hello -Wl,--heap=0x1000000 24991@end example 24992 24993This sets the heap reserve size to 0x1000000 bytes. Note that with 24994@code{-Wl} option it is not possible to set the heap commit size 24995because the comma is a separator for this option. 24996@end itemize 24997 24998@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics 24999@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{209}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{20a} 25000@subsection Windows Specific Add-Ons 25001 25002 25003This section describes the Windows specific add-ons. 25004 25005@menu 25006* Win32Ada:: 25007* wPOSIX:: 25008 25009@end menu 25010 25011@node Win32Ada,wPOSIX,,Windows Specific Add-Ons 25012@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20b}@anchor{gnat_ugn/platform_specific_information id41}@anchor{20c} 25013@subsubsection Win32Ada 25014 25015 25016Win32Ada is a binding for the Microsoft Win32 API. This binding can be 25017easily installed from the provided installer. To use the Win32Ada 25018binding you need to use a project file, and adding a single with_clause 25019will give you full access to the Win32Ada binding sources and ensure 25020that the proper libraries are passed to the linker. 25021 25022@quotation 25023 25024@example 25025with "win32ada"; 25026project P is 25027 for Sources use ...; 25028end P; 25029@end example 25030@end quotation 25031 25032To build the application you just need to call gprbuild for the 25033application's project, here p.gpr: 25034 25035@quotation 25036 25037@example 25038gprbuild p.gpr 25039@end example 25040@end quotation 25041 25042@node wPOSIX,,Win32Ada,Windows Specific Add-Ons 25043@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{20e} 25044@subsubsection wPOSIX 25045 25046 25047wPOSIX is a minimal POSIX binding whose goal is to help with building 25048cross-platforms applications. This binding is not complete though, as 25049the Win32 API does not provide the necessary support for all POSIX APIs. 25050 25051To use the wPOSIX binding you need to use a project file, and adding 25052a single with_clause will give you full access to the wPOSIX binding 25053sources and ensure that the proper libraries are passed to the linker. 25054 25055@quotation 25056 25057@example 25058with "wposix"; 25059project P is 25060 for Sources use ...; 25061end P; 25062@end example 25063@end quotation 25064 25065To build the application you just need to call gprbuild for the 25066application's project, here p.gpr: 25067 25068@quotation 25069 25070@example 25071gprbuild p.gpr 25072@end example 25073@end quotation 25074 25075@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information 25076@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{20f}@anchor{gnat_ugn/platform_specific_information id43}@anchor{210} 25077@section Mac OS Topics 25078 25079 25080@geindex OS X 25081 25082This section describes topics that are specific to Apple's OS X 25083platform. 25084 25085@menu 25086* Codesigning the Debugger:: 25087 25088@end menu 25089 25090@node Codesigning the Debugger,,,Mac OS Topics 25091@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{211} 25092@subsection Codesigning the Debugger 25093 25094 25095The Darwin Kernel requires the debugger to have special permissions 25096before it is allowed to control other processes. These permissions 25097are granted by codesigning the GDB executable. Without these 25098permissions, the debugger will report error messages such as: 25099 25100@example 25101Starting program: /x/y/foo 25102Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5). 25103(please check gdb is codesigned - see taskgated(8)) 25104@end example 25105 25106Codesigning requires a certificate. The following procedure explains 25107how to create one: 25108 25109 25110@itemize * 25111 25112@item 25113Start the Keychain Access application (in 25114/Applications/Utilities/Keychain Access.app) 25115 25116@item 25117Select the Keychain Access -> Certificate Assistant -> 25118Create a Certificate... menu 25119 25120@item 25121Then: 25122 25123 25124@itemize * 25125 25126@item 25127Choose a name for the new certificate (this procedure will use 25128"gdb-cert" as an example) 25129 25130@item 25131Set "Identity Type" to "Self Signed Root" 25132 25133@item 25134Set "Certificate Type" to "Code Signing" 25135 25136@item 25137Activate the "Let me override defaults" option 25138@end itemize 25139 25140@item 25141Click several times on "Continue" until the "Specify a Location 25142For The Certificate" screen appears, then set "Keychain" to "System" 25143 25144@item 25145Click on "Continue" until the certificate is created 25146 25147@item 25148Finally, in the view, double-click on the new certificate, 25149and set "When using this certificate" to "Always Trust" 25150 25151@item 25152Exit the Keychain Access application and restart the computer 25153(this is unfortunately required) 25154@end itemize 25155 25156Once a certificate has been created, the debugger can be codesigned 25157as follow. In a Terminal, run the following command: 25158 25159@quotation 25160 25161@example 25162$ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb 25163@end example 25164@end quotation 25165 25166where "gdb-cert" should be replaced by the actual certificate 25167name chosen above, and <gnat_install_prefix> should be replaced by 25168the location where you installed GNAT. Also, be sure that users are 25169in the Unix group @code{_developer}. 25170 25171@node Example of Binder Output File,Elaboration Order Handling in GNAT,Platform-Specific Information,Top 25172@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{212}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{213} 25173@chapter Example of Binder Output File 25174 25175 25176@geindex Binder output (example) 25177 25178This Appendix displays the source code for the output file 25179generated by @emph{gnatbind} for a simple 'Hello World' program. 25180Comments have been added for clarification purposes. 25181 25182@example 25183-- The package is called Ada_Main unless this name is actually used 25184-- as a unit name in the partition, in which case some other unique 25185-- name is used. 25186 25187pragma Ada_95; 25188with System; 25189package ada_main is 25190 pragma Warnings (Off); 25191 25192 -- The main program saves the parameters (argument count, 25193 -- argument values, environment pointer) in global variables 25194 -- for later access by other units including 25195 -- Ada.Command_Line. 25196 25197 gnat_argc : Integer; 25198 gnat_argv : System.Address; 25199 gnat_envp : System.Address; 25200 25201 -- The actual variables are stored in a library routine. This 25202 -- is useful for some shared library situations, where there 25203 -- are problems if variables are not in the library. 25204 25205 pragma Import (C, gnat_argc); 25206 pragma Import (C, gnat_argv); 25207 pragma Import (C, gnat_envp); 25208 25209 -- The exit status is similarly an external location 25210 25211 gnat_exit_status : Integer; 25212 pragma Import (C, gnat_exit_status); 25213 25214 GNAT_Version : constant String := 25215 "GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL; 25216 pragma Export (C, GNAT_Version, "__gnat_version"); 25217 25218 Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL; 25219 pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name"); 25220 25221 -- This is the generated adainit routine that performs 25222 -- initialization at the start of execution. In the case 25223 -- where Ada is the main program, this main program makes 25224 -- a call to adainit at program startup. 25225 25226 procedure adainit; 25227 pragma Export (C, adainit, "adainit"); 25228 25229 -- This is the generated adafinal routine that performs 25230 -- finalization at the end of execution. In the case where 25231 -- Ada is the main program, this main program makes a call 25232 -- to adafinal at program termination. 25233 25234 procedure adafinal; 25235 pragma Export (C, adafinal, "adafinal"); 25236 25237 -- This routine is called at the start of execution. It is 25238 -- a dummy routine that is used by the debugger to breakpoint 25239 -- at the start of execution. 25240 25241 -- This is the actual generated main program (it would be 25242 -- suppressed if the no main program switch were used). As 25243 -- required by standard system conventions, this program has 25244 -- the external name main. 25245 25246 function main 25247 (argc : Integer; 25248 argv : System.Address; 25249 envp : System.Address) 25250 return Integer; 25251 pragma Export (C, main, "main"); 25252 25253 -- The following set of constants give the version 25254 -- identification values for every unit in the bound 25255 -- partition. This identification is computed from all 25256 -- dependent semantic units, and corresponds to the 25257 -- string that would be returned by use of the 25258 -- Body_Version or Version attributes. 25259 25260 -- The following Export pragmas export the version numbers 25261 -- with symbolic names ending in B (for body) or S 25262 -- (for spec) so that they can be located in a link. The 25263 -- information provided here is sufficient to track down 25264 -- the exact versions of units used in a given build. 25265 25266 type Version_32 is mod 2 ** 32; 25267 u00001 : constant Version_32 := 16#8ad6e54a#; 25268 pragma Export (C, u00001, "helloB"); 25269 u00002 : constant Version_32 := 16#fbff4c67#; 25270 pragma Export (C, u00002, "system__standard_libraryB"); 25271 u00003 : constant Version_32 := 16#1ec6fd90#; 25272 pragma Export (C, u00003, "system__standard_libraryS"); 25273 u00004 : constant Version_32 := 16#3ffc8e18#; 25274 pragma Export (C, u00004, "adaS"); 25275 u00005 : constant Version_32 := 16#28f088c2#; 25276 pragma Export (C, u00005, "ada__text_ioB"); 25277 u00006 : constant Version_32 := 16#f372c8ac#; 25278 pragma Export (C, u00006, "ada__text_ioS"); 25279 u00007 : constant Version_32 := 16#2c143749#; 25280 pragma Export (C, u00007, "ada__exceptionsB"); 25281 u00008 : constant Version_32 := 16#f4f0cce8#; 25282 pragma Export (C, u00008, "ada__exceptionsS"); 25283 u00009 : constant Version_32 := 16#a46739c0#; 25284 pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB"); 25285 u00010 : constant Version_32 := 16#3aac8c92#; 25286 pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS"); 25287 u00011 : constant Version_32 := 16#1d274481#; 25288 pragma Export (C, u00011, "systemS"); 25289 u00012 : constant Version_32 := 16#a207fefe#; 25290 pragma Export (C, u00012, "system__soft_linksB"); 25291 u00013 : constant Version_32 := 16#467d9556#; 25292 pragma Export (C, u00013, "system__soft_linksS"); 25293 u00014 : constant Version_32 := 16#b01dad17#; 25294 pragma Export (C, u00014, "system__parametersB"); 25295 u00015 : constant Version_32 := 16#630d49fe#; 25296 pragma Export (C, u00015, "system__parametersS"); 25297 u00016 : constant Version_32 := 16#b19b6653#; 25298 pragma Export (C, u00016, "system__secondary_stackB"); 25299 u00017 : constant Version_32 := 16#b6468be8#; 25300 pragma Export (C, u00017, "system__secondary_stackS"); 25301 u00018 : constant Version_32 := 16#39a03df9#; 25302 pragma Export (C, u00018, "system__storage_elementsB"); 25303 u00019 : constant Version_32 := 16#30e40e85#; 25304 pragma Export (C, u00019, "system__storage_elementsS"); 25305 u00020 : constant Version_32 := 16#41837d1e#; 25306 pragma Export (C, u00020, "system__stack_checkingB"); 25307 u00021 : constant Version_32 := 16#93982f69#; 25308 pragma Export (C, u00021, "system__stack_checkingS"); 25309 u00022 : constant Version_32 := 16#393398c1#; 25310 pragma Export (C, u00022, "system__exception_tableB"); 25311 u00023 : constant Version_32 := 16#b33e2294#; 25312 pragma Export (C, u00023, "system__exception_tableS"); 25313 u00024 : constant Version_32 := 16#ce4af020#; 25314 pragma Export (C, u00024, "system__exceptionsB"); 25315 u00025 : constant Version_32 := 16#75442977#; 25316 pragma Export (C, u00025, "system__exceptionsS"); 25317 u00026 : constant Version_32 := 16#37d758f1#; 25318 pragma Export (C, u00026, "system__exceptions__machineS"); 25319 u00027 : constant Version_32 := 16#b895431d#; 25320 pragma Export (C, u00027, "system__exceptions_debugB"); 25321 u00028 : constant Version_32 := 16#aec55d3f#; 25322 pragma Export (C, u00028, "system__exceptions_debugS"); 25323 u00029 : constant Version_32 := 16#570325c8#; 25324 pragma Export (C, u00029, "system__img_intB"); 25325 u00030 : constant Version_32 := 16#1ffca443#; 25326 pragma Export (C, u00030, "system__img_intS"); 25327 u00031 : constant Version_32 := 16#b98c3e16#; 25328 pragma Export (C, u00031, "system__tracebackB"); 25329 u00032 : constant Version_32 := 16#831a9d5a#; 25330 pragma Export (C, u00032, "system__tracebackS"); 25331 u00033 : constant Version_32 := 16#9ed49525#; 25332 pragma Export (C, u00033, "system__traceback_entriesB"); 25333 u00034 : constant Version_32 := 16#1d7cb2f1#; 25334 pragma Export (C, u00034, "system__traceback_entriesS"); 25335 u00035 : constant Version_32 := 16#8c33a517#; 25336 pragma Export (C, u00035, "system__wch_conB"); 25337 u00036 : constant Version_32 := 16#065a6653#; 25338 pragma Export (C, u00036, "system__wch_conS"); 25339 u00037 : constant Version_32 := 16#9721e840#; 25340 pragma Export (C, u00037, "system__wch_stwB"); 25341 u00038 : constant Version_32 := 16#2b4b4a52#; 25342 pragma Export (C, u00038, "system__wch_stwS"); 25343 u00039 : constant Version_32 := 16#92b797cb#; 25344 pragma Export (C, u00039, "system__wch_cnvB"); 25345 u00040 : constant Version_32 := 16#09eddca0#; 25346 pragma Export (C, u00040, "system__wch_cnvS"); 25347 u00041 : constant Version_32 := 16#6033a23f#; 25348 pragma Export (C, u00041, "interfacesS"); 25349 u00042 : constant Version_32 := 16#ece6fdb6#; 25350 pragma Export (C, u00042, "system__wch_jisB"); 25351 u00043 : constant Version_32 := 16#899dc581#; 25352 pragma Export (C, u00043, "system__wch_jisS"); 25353 u00044 : constant Version_32 := 16#10558b11#; 25354 pragma Export (C, u00044, "ada__streamsB"); 25355 u00045 : constant Version_32 := 16#2e6701ab#; 25356 pragma Export (C, u00045, "ada__streamsS"); 25357 u00046 : constant Version_32 := 16#db5c917c#; 25358 pragma Export (C, u00046, "ada__io_exceptionsS"); 25359 u00047 : constant Version_32 := 16#12c8cd7d#; 25360 pragma Export (C, u00047, "ada__tagsB"); 25361 u00048 : constant Version_32 := 16#ce72c228#; 25362 pragma Export (C, u00048, "ada__tagsS"); 25363 u00049 : constant Version_32 := 16#c3335bfd#; 25364 pragma Export (C, u00049, "system__htableB"); 25365 u00050 : constant Version_32 := 16#99e5f76b#; 25366 pragma Export (C, u00050, "system__htableS"); 25367 u00051 : constant Version_32 := 16#089f5cd0#; 25368 pragma Export (C, u00051, "system__string_hashB"); 25369 u00052 : constant Version_32 := 16#3bbb9c15#; 25370 pragma Export (C, u00052, "system__string_hashS"); 25371 u00053 : constant Version_32 := 16#807fe041#; 25372 pragma Export (C, u00053, "system__unsigned_typesS"); 25373 u00054 : constant Version_32 := 16#d27be59e#; 25374 pragma Export (C, u00054, "system__val_lluB"); 25375 u00055 : constant Version_32 := 16#fa8db733#; 25376 pragma Export (C, u00055, "system__val_lluS"); 25377 u00056 : constant Version_32 := 16#27b600b2#; 25378 pragma Export (C, u00056, "system__val_utilB"); 25379 u00057 : constant Version_32 := 16#b187f27f#; 25380 pragma Export (C, u00057, "system__val_utilS"); 25381 u00058 : constant Version_32 := 16#d1060688#; 25382 pragma Export (C, u00058, "system__case_utilB"); 25383 u00059 : constant Version_32 := 16#392e2d56#; 25384 pragma Export (C, u00059, "system__case_utilS"); 25385 u00060 : constant Version_32 := 16#84a27f0d#; 25386 pragma Export (C, u00060, "interfaces__c_streamsB"); 25387 u00061 : constant Version_32 := 16#8bb5f2c0#; 25388 pragma Export (C, u00061, "interfaces__c_streamsS"); 25389 u00062 : constant Version_32 := 16#6db6928f#; 25390 pragma Export (C, u00062, "system__crtlS"); 25391 u00063 : constant Version_32 := 16#4e6a342b#; 25392 pragma Export (C, u00063, "system__file_ioB"); 25393 u00064 : constant Version_32 := 16#ba56a5e4#; 25394 pragma Export (C, u00064, "system__file_ioS"); 25395 u00065 : constant Version_32 := 16#b7ab275c#; 25396 pragma Export (C, u00065, "ada__finalizationB"); 25397 u00066 : constant Version_32 := 16#19f764ca#; 25398 pragma Export (C, u00066, "ada__finalizationS"); 25399 u00067 : constant Version_32 := 16#95817ed8#; 25400 pragma Export (C, u00067, "system__finalization_rootB"); 25401 u00068 : constant Version_32 := 16#52d53711#; 25402 pragma Export (C, u00068, "system__finalization_rootS"); 25403 u00069 : constant Version_32 := 16#769e25e6#; 25404 pragma Export (C, u00069, "interfaces__cB"); 25405 u00070 : constant Version_32 := 16#4a38bedb#; 25406 pragma Export (C, u00070, "interfaces__cS"); 25407 u00071 : constant Version_32 := 16#07e6ee66#; 25408 pragma Export (C, u00071, "system__os_libB"); 25409 u00072 : constant Version_32 := 16#d7b69782#; 25410 pragma Export (C, u00072, "system__os_libS"); 25411 u00073 : constant Version_32 := 16#1a817b8e#; 25412 pragma Export (C, u00073, "system__stringsB"); 25413 u00074 : constant Version_32 := 16#639855e7#; 25414 pragma Export (C, u00074, "system__stringsS"); 25415 u00075 : constant Version_32 := 16#e0b8de29#; 25416 pragma Export (C, u00075, "system__file_control_blockS"); 25417 u00076 : constant Version_32 := 16#b5b2aca1#; 25418 pragma Export (C, u00076, "system__finalization_mastersB"); 25419 u00077 : constant Version_32 := 16#69316dc1#; 25420 pragma Export (C, u00077, "system__finalization_mastersS"); 25421 u00078 : constant Version_32 := 16#57a37a42#; 25422 pragma Export (C, u00078, "system__address_imageB"); 25423 u00079 : constant Version_32 := 16#bccbd9bb#; 25424 pragma Export (C, u00079, "system__address_imageS"); 25425 u00080 : constant Version_32 := 16#7268f812#; 25426 pragma Export (C, u00080, "system__img_boolB"); 25427 u00081 : constant Version_32 := 16#e8fe356a#; 25428 pragma Export (C, u00081, "system__img_boolS"); 25429 u00082 : constant Version_32 := 16#d7aac20c#; 25430 pragma Export (C, u00082, "system__ioB"); 25431 u00083 : constant Version_32 := 16#8365b3ce#; 25432 pragma Export (C, u00083, "system__ioS"); 25433 u00084 : constant Version_32 := 16#6d4d969a#; 25434 pragma Export (C, u00084, "system__storage_poolsB"); 25435 u00085 : constant Version_32 := 16#e87cc305#; 25436 pragma Export (C, u00085, "system__storage_poolsS"); 25437 u00086 : constant Version_32 := 16#e34550ca#; 25438 pragma Export (C, u00086, "system__pool_globalB"); 25439 u00087 : constant Version_32 := 16#c88d2d16#; 25440 pragma Export (C, u00087, "system__pool_globalS"); 25441 u00088 : constant Version_32 := 16#9d39c675#; 25442 pragma Export (C, u00088, "system__memoryB"); 25443 u00089 : constant Version_32 := 16#445a22b5#; 25444 pragma Export (C, u00089, "system__memoryS"); 25445 u00090 : constant Version_32 := 16#6a859064#; 25446 pragma Export (C, u00090, "system__storage_pools__subpoolsB"); 25447 u00091 : constant Version_32 := 16#e3b008dc#; 25448 pragma Export (C, u00091, "system__storage_pools__subpoolsS"); 25449 u00092 : constant Version_32 := 16#63f11652#; 25450 pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB"); 25451 u00093 : constant Version_32 := 16#fe2f4b3a#; 25452 pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS"); 25453 25454 -- BEGIN ELABORATION ORDER 25455 -- ada%s 25456 -- interfaces%s 25457 -- system%s 25458 -- system.case_util%s 25459 -- system.case_util%b 25460 -- system.htable%s 25461 -- system.img_bool%s 25462 -- system.img_bool%b 25463 -- system.img_int%s 25464 -- system.img_int%b 25465 -- system.io%s 25466 -- system.io%b 25467 -- system.parameters%s 25468 -- system.parameters%b 25469 -- system.crtl%s 25470 -- interfaces.c_streams%s 25471 -- interfaces.c_streams%b 25472 -- system.standard_library%s 25473 -- system.exceptions_debug%s 25474 -- system.exceptions_debug%b 25475 -- system.storage_elements%s 25476 -- system.storage_elements%b 25477 -- system.stack_checking%s 25478 -- system.stack_checking%b 25479 -- system.string_hash%s 25480 -- system.string_hash%b 25481 -- system.htable%b 25482 -- system.strings%s 25483 -- system.strings%b 25484 -- system.os_lib%s 25485 -- system.traceback_entries%s 25486 -- system.traceback_entries%b 25487 -- ada.exceptions%s 25488 -- system.soft_links%s 25489 -- system.unsigned_types%s 25490 -- system.val_llu%s 25491 -- system.val_util%s 25492 -- system.val_util%b 25493 -- system.val_llu%b 25494 -- system.wch_con%s 25495 -- system.wch_con%b 25496 -- system.wch_cnv%s 25497 -- system.wch_jis%s 25498 -- system.wch_jis%b 25499 -- system.wch_cnv%b 25500 -- system.wch_stw%s 25501 -- system.wch_stw%b 25502 -- ada.exceptions.last_chance_handler%s 25503 -- ada.exceptions.last_chance_handler%b 25504 -- system.address_image%s 25505 -- system.exception_table%s 25506 -- system.exception_table%b 25507 -- ada.io_exceptions%s 25508 -- ada.tags%s 25509 -- ada.streams%s 25510 -- ada.streams%b 25511 -- interfaces.c%s 25512 -- system.exceptions%s 25513 -- system.exceptions%b 25514 -- system.exceptions.machine%s 25515 -- system.finalization_root%s 25516 -- system.finalization_root%b 25517 -- ada.finalization%s 25518 -- ada.finalization%b 25519 -- system.storage_pools%s 25520 -- system.storage_pools%b 25521 -- system.finalization_masters%s 25522 -- system.storage_pools.subpools%s 25523 -- system.storage_pools.subpools.finalization%s 25524 -- system.storage_pools.subpools.finalization%b 25525 -- system.memory%s 25526 -- system.memory%b 25527 -- system.standard_library%b 25528 -- system.pool_global%s 25529 -- system.pool_global%b 25530 -- system.file_control_block%s 25531 -- system.file_io%s 25532 -- system.secondary_stack%s 25533 -- system.file_io%b 25534 -- system.storage_pools.subpools%b 25535 -- system.finalization_masters%b 25536 -- interfaces.c%b 25537 -- ada.tags%b 25538 -- system.soft_links%b 25539 -- system.os_lib%b 25540 -- system.secondary_stack%b 25541 -- system.address_image%b 25542 -- system.traceback%s 25543 -- ada.exceptions%b 25544 -- system.traceback%b 25545 -- ada.text_io%s 25546 -- ada.text_io%b 25547 -- hello%b 25548 -- END ELABORATION ORDER 25549 25550end ada_main; 25551@end example 25552 25553@example 25554pragma Ada_95; 25555-- The following source file name pragmas allow the generated file 25556-- names to be unique for different main programs. They are needed 25557-- since the package name will always be Ada_Main. 25558 25559pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); 25560pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); 25561 25562pragma Suppress (Overflow_Check); 25563with Ada.Exceptions; 25564 25565-- Generated package body for Ada_Main starts here 25566 25567package body ada_main is 25568 pragma Warnings (Off); 25569 25570 -- These values are reference counter associated to units which have 25571 -- been elaborated. It is also used to avoid elaborating the 25572 -- same unit twice. 25573 25574 E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E"); 25575 E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E"); 25576 E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E"); 25577 E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E"); 25578 E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E"); 25579 E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E"); 25580 E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E"); 25581 E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E"); 25582 E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E"); 25583 E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E"); 25584 E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E"); 25585 E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E"); 25586 E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E"); 25587 E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E"); 25588 E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E"); 25589 E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E"); 25590 E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E"); 25591 E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E"); 25592 25593 Local_Priority_Specific_Dispatching : constant String := ""; 25594 Local_Interrupt_States : constant String := ""; 25595 25596 Is_Elaborated : Boolean := False; 25597 25598 procedure finalize_library is 25599 begin 25600 E06 := E06 - 1; 25601 declare 25602 procedure F1; 25603 pragma Import (Ada, F1, "ada__text_io__finalize_spec"); 25604 begin 25605 F1; 25606 end; 25607 E77 := E77 - 1; 25608 E91 := E91 - 1; 25609 declare 25610 procedure F2; 25611 pragma Import (Ada, F2, "system__file_io__finalize_body"); 25612 begin 25613 E64 := E64 - 1; 25614 F2; 25615 end; 25616 declare 25617 procedure F3; 25618 pragma Import (Ada, F3, "system__file_control_block__finalize_spec"); 25619 begin 25620 E75 := E75 - 1; 25621 F3; 25622 end; 25623 E87 := E87 - 1; 25624 declare 25625 procedure F4; 25626 pragma Import (Ada, F4, "system__pool_global__finalize_spec"); 25627 begin 25628 F4; 25629 end; 25630 declare 25631 procedure F5; 25632 pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec"); 25633 begin 25634 F5; 25635 end; 25636 declare 25637 procedure F6; 25638 pragma Import (Ada, F6, "system__finalization_masters__finalize_spec"); 25639 begin 25640 F6; 25641 end; 25642 declare 25643 procedure Reraise_Library_Exception_If_Any; 25644 pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any"); 25645 begin 25646 Reraise_Library_Exception_If_Any; 25647 end; 25648 end finalize_library; 25649 25650 ------------- 25651 -- adainit -- 25652 ------------- 25653 25654 procedure adainit is 25655 25656 Main_Priority : Integer; 25657 pragma Import (C, Main_Priority, "__gl_main_priority"); 25658 Time_Slice_Value : Integer; 25659 pragma Import (C, Time_Slice_Value, "__gl_time_slice_val"); 25660 WC_Encoding : Character; 25661 pragma Import (C, WC_Encoding, "__gl_wc_encoding"); 25662 Locking_Policy : Character; 25663 pragma Import (C, Locking_Policy, "__gl_locking_policy"); 25664 Queuing_Policy : Character; 25665 pragma Import (C, Queuing_Policy, "__gl_queuing_policy"); 25666 Task_Dispatching_Policy : Character; 25667 pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy"); 25668 Priority_Specific_Dispatching : System.Address; 25669 pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching"); 25670 Num_Specific_Dispatching : Integer; 25671 pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching"); 25672 Main_CPU : Integer; 25673 pragma Import (C, Main_CPU, "__gl_main_cpu"); 25674 Interrupt_States : System.Address; 25675 pragma Import (C, Interrupt_States, "__gl_interrupt_states"); 25676 Num_Interrupt_States : Integer; 25677 pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states"); 25678 Unreserve_All_Interrupts : Integer; 25679 pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts"); 25680 Detect_Blocking : Integer; 25681 pragma Import (C, Detect_Blocking, "__gl_detect_blocking"); 25682 Default_Stack_Size : Integer; 25683 pragma Import (C, Default_Stack_Size, "__gl_default_stack_size"); 25684 Leap_Seconds_Support : Integer; 25685 pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support"); 25686 25687 procedure Runtime_Initialize; 25688 pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize"); 25689 25690 Finalize_Library_Objects : No_Param_Proc; 25691 pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects"); 25692 25693 -- Start of processing for adainit 25694 25695 begin 25696 25697 -- Record various information for this partition. The values 25698 -- are derived by the binder from information stored in the ali 25699 -- files by the compiler. 25700 25701 if Is_Elaborated then 25702 return; 25703 end if; 25704 Is_Elaborated := True; 25705 Main_Priority := -1; 25706 Time_Slice_Value := -1; 25707 WC_Encoding := 'b'; 25708 Locking_Policy := ' '; 25709 Queuing_Policy := ' '; 25710 Task_Dispatching_Policy := ' '; 25711 Priority_Specific_Dispatching := 25712 Local_Priority_Specific_Dispatching'Address; 25713 Num_Specific_Dispatching := 0; 25714 Main_CPU := -1; 25715 Interrupt_States := Local_Interrupt_States'Address; 25716 Num_Interrupt_States := 0; 25717 Unreserve_All_Interrupts := 0; 25718 Detect_Blocking := 0; 25719 Default_Stack_Size := -1; 25720 Leap_Seconds_Support := 0; 25721 25722 Runtime_Initialize; 25723 25724 Finalize_Library_Objects := finalize_library'access; 25725 25726 -- Now we have the elaboration calls for all units in the partition. 25727 -- The Elab_Spec and Elab_Body attributes generate references to the 25728 -- implicit elaboration procedures generated by the compiler for 25729 -- each unit that requires elaboration. Increment a counter of 25730 -- reference for each unit. 25731 25732 System.Soft_Links'Elab_Spec; 25733 System.Exception_Table'Elab_Body; 25734 E23 := E23 + 1; 25735 Ada.Io_Exceptions'Elab_Spec; 25736 E46 := E46 + 1; 25737 Ada.Tags'Elab_Spec; 25738 Ada.Streams'Elab_Spec; 25739 E45 := E45 + 1; 25740 Interfaces.C'Elab_Spec; 25741 System.Exceptions'Elab_Spec; 25742 E25 := E25 + 1; 25743 System.Finalization_Root'Elab_Spec; 25744 E68 := E68 + 1; 25745 Ada.Finalization'Elab_Spec; 25746 E66 := E66 + 1; 25747 System.Storage_Pools'Elab_Spec; 25748 E85 := E85 + 1; 25749 System.Finalization_Masters'Elab_Spec; 25750 System.Storage_Pools.Subpools'Elab_Spec; 25751 System.Pool_Global'Elab_Spec; 25752 E87 := E87 + 1; 25753 System.File_Control_Block'Elab_Spec; 25754 E75 := E75 + 1; 25755 System.File_Io'Elab_Body; 25756 E64 := E64 + 1; 25757 E91 := E91 + 1; 25758 System.Finalization_Masters'Elab_Body; 25759 E77 := E77 + 1; 25760 E70 := E70 + 1; 25761 Ada.Tags'Elab_Body; 25762 E48 := E48 + 1; 25763 System.Soft_Links'Elab_Body; 25764 E13 := E13 + 1; 25765 System.Os_Lib'Elab_Body; 25766 E72 := E72 + 1; 25767 System.Secondary_Stack'Elab_Body; 25768 E17 := E17 + 1; 25769 Ada.Text_Io'Elab_Spec; 25770 Ada.Text_Io'Elab_Body; 25771 E06 := E06 + 1; 25772 end adainit; 25773 25774 -------------- 25775 -- adafinal -- 25776 -------------- 25777 25778 procedure adafinal is 25779 procedure s_stalib_adafinal; 25780 pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal"); 25781 25782 procedure Runtime_Finalize; 25783 pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize"); 25784 25785 begin 25786 if not Is_Elaborated then 25787 return; 25788 end if; 25789 Is_Elaborated := False; 25790 Runtime_Finalize; 25791 s_stalib_adafinal; 25792 end adafinal; 25793 25794 -- We get to the main program of the partition by using 25795 -- pragma Import because if we try to with the unit and 25796 -- call it Ada style, then not only do we waste time 25797 -- recompiling it, but also, we don't really know the right 25798 -- switches (e.g.@@: identifier character set) to be used 25799 -- to compile it. 25800 25801 procedure Ada_Main_Program; 25802 pragma Import (Ada, Ada_Main_Program, "_ada_hello"); 25803 25804 ---------- 25805 -- main -- 25806 ---------- 25807 25808 -- main is actually a function, as in the ANSI C standard, 25809 -- defined to return the exit status. The three parameters 25810 -- are the argument count, argument values and environment 25811 -- pointer. 25812 25813 function main 25814 (argc : Integer; 25815 argv : System.Address; 25816 envp : System.Address) 25817 return Integer 25818 is 25819 -- The initialize routine performs low level system 25820 -- initialization using a standard library routine which 25821 -- sets up signal handling and performs any other 25822 -- required setup. The routine can be found in file 25823 -- a-init.c. 25824 25825 procedure initialize; 25826 pragma Import (C, initialize, "__gnat_initialize"); 25827 25828 -- The finalize routine performs low level system 25829 -- finalization using a standard library routine. The 25830 -- routine is found in file a-final.c and in the standard 25831 -- distribution is a dummy routine that does nothing, so 25832 -- really this is a hook for special user finalization. 25833 25834 procedure finalize; 25835 pragma Import (C, finalize, "__gnat_finalize"); 25836 25837 -- The following is to initialize the SEH exceptions 25838 25839 SEH : aliased array (1 .. 2) of Integer; 25840 25841 Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address; 25842 pragma Volatile (Ensure_Reference); 25843 25844 -- Start of processing for main 25845 25846 begin 25847 -- Save global variables 25848 25849 gnat_argc := argc; 25850 gnat_argv := argv; 25851 gnat_envp := envp; 25852 25853 -- Call low level system initialization 25854 25855 Initialize (SEH'Address); 25856 25857 -- Call our generated Ada initialization routine 25858 25859 adainit; 25860 25861 -- Now we call the main program of the partition 25862 25863 Ada_Main_Program; 25864 25865 -- Perform Ada finalization 25866 25867 adafinal; 25868 25869 -- Perform low level system finalization 25870 25871 Finalize; 25872 25873 -- Return the proper exit status 25874 return (gnat_exit_status); 25875 end; 25876 25877-- This section is entirely comments, so it has no effect on the 25878-- compilation of the Ada_Main package. It provides the list of 25879-- object files and linker options, as well as some standard 25880-- libraries needed for the link. The gnatlink utility parses 25881-- this b~hello.adb file to read these comment lines to generate 25882-- the appropriate command line arguments for the call to the 25883-- system linker. The BEGIN/END lines are used for sentinels for 25884-- this parsing operation. 25885 25886-- The exact file names will of course depend on the environment, 25887-- host/target and location of files on the host system. 25888 25889-- BEGIN Object file/option list 25890 -- ./hello.o 25891 -- -L./ 25892 -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ 25893 -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a 25894-- END Object file/option list 25895 25896end ada_main; 25897@end example 25898 25899The Ada code in the above example is exactly what is generated by the 25900binder. We have added comments to more clearly indicate the function 25901of each part of the generated @code{Ada_Main} package. 25902 25903The code is standard Ada in all respects, and can be processed by any 25904tools that handle Ada. In particular, it is possible to use the debugger 25905in Ada mode to debug the generated @code{Ada_Main} package. For example, 25906suppose that for reasons that you do not understand, your program is crashing 25907during elaboration of the body of @code{Ada.Text_IO}. To locate this bug, 25908you can place a breakpoint on the call: 25909 25910@quotation 25911 25912@example 25913Ada.Text_Io'Elab_Body; 25914@end example 25915@end quotation 25916 25917and trace the elaboration routine for this package to find out where 25918the problem might be (more usually of course you would be debugging 25919elaboration code in your own application). 25920 25921@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit 25922 25923@node Elaboration Order Handling in GNAT,Inline Assembler,Example of Binder Output File,Top 25924@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{214}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{215} 25925@chapter Elaboration Order Handling in GNAT 25926 25927 25928@geindex Order of elaboration 25929 25930@geindex Elaboration control 25931 25932This appendix describes the handling of elaboration code in Ada and GNAT, and 25933discusses how the order of elaboration of program units can be controlled in 25934GNAT, either automatically or with explicit programming features. 25935 25936@menu 25937* Elaboration Code:: 25938* Elaboration Order:: 25939* Checking the Elaboration Order:: 25940* Controlling the Elaboration Order in Ada:: 25941* Controlling the Elaboration Order in GNAT:: 25942* Mixing Elaboration Models:: 25943* ABE Diagnostics:: 25944* SPARK Diagnostics:: 25945* Elaboration Circularities:: 25946* Resolving Elaboration Circularities:: 25947* Elaboration-related Compiler Switches:: 25948* Summary of Procedures for Elaboration Control:: 25949* Inspecting the Chosen Elaboration Order:: 25950 25951@end menu 25952 25953@node Elaboration Code,Elaboration Order,,Elaboration Order Handling in GNAT 25954@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{217} 25955@section Elaboration Code 25956 25957 25958Ada defines the term @emph{execution} as the process by which a construct achieves 25959its run-time effect. This process is also referred to as @strong{elaboration} for 25960declarations and @emph{evaluation} for expressions. 25961 25962The execution model in Ada allows for certain sections of an Ada program to be 25963executed prior to execution of the program itself, primarily with the intent of 25964initializing data. These sections are referred to as @strong{elaboration code}. 25965Elaboration code is executed as follows: 25966 25967 25968@itemize * 25969 25970@item 25971All partitions of an Ada program are executed in parallel with one another, 25972possibly in a separate address space, and possibly on a separate computer. 25973 25974@item 25975The execution of a partition involves running the environment task for that 25976partition. 25977 25978@item 25979The environment task executes all elaboration code (if available) for all 25980units within that partition. This code is said to be executed at 25981@strong{elaboration time}. 25982 25983@item 25984The environment task executes the Ada program (if available) for that 25985partition. 25986@end itemize 25987 25988In addition to the Ada terminology, this appendix defines the following terms: 25989 25990 25991@itemize * 25992 25993@item 25994@emph{Invocation} 25995 25996The act of calling a subprogram, instantiating a generic, or activating a 25997task. 25998 25999@item 26000@emph{Scenario} 26001 26002A construct that is elaborated or invoked by elaboration code is referred to 26003as an @emph{elaboration scenario} or simply a @strong{scenario}. GNAT recognizes the 26004following scenarios: 26005 26006 26007@itemize - 26008 26009@item 26010@code{'Access} of entries, operators, and subprograms 26011 26012@item 26013Activation of tasks 26014 26015@item 26016Calls to entries, operators, and subprograms 26017 26018@item 26019Instantiations of generic templates 26020@end itemize 26021 26022@item 26023@emph{Target} 26024 26025A construct elaborated by a scenario is referred to as @emph{elaboration target} 26026or simply @strong{target}. GNAT recognizes the following targets: 26027 26028 26029@itemize - 26030 26031@item 26032For @code{'Access} of entries, operators, and subprograms, the target is the 26033entry, operator, or subprogram being aliased. 26034 26035@item 26036For activation of tasks, the target is the task body 26037 26038@item 26039For calls to entries, operators, and subprograms, the target is the entry, 26040operator, or subprogram being invoked. 26041 26042@item 26043For instantiations of generic templates, the target is the generic template 26044being instantiated. 26045@end itemize 26046@end itemize 26047 26048Elaboration code may appear in two distinct contexts: 26049 26050 26051@itemize * 26052 26053@item 26054@emph{Library level} 26055 26056A scenario appears at the library level when it is encapsulated by a package 26057[body] compilation unit, ignoring any other package [body] declarations in 26058between. 26059 26060@example 26061with Server; 26062package Client is 26063 procedure Proc; 26064 26065 package Nested is 26066 Val : ... := Server.Func; 26067 end Nested; 26068end Client; 26069@end example 26070 26071In the example above, the call to @code{Server.Func} is an elaboration scenario 26072because it appears at the library level of package @code{Client}. Note that the 26073declaration of package @code{Nested} is ignored according to the definition 26074given above. As a result, the call to @code{Server.Func} will be invoked when 26075the spec of unit @code{Client} is elaborated. 26076 26077@item 26078@emph{Package body statements} 26079 26080A scenario appears within the statement sequence of a package body when it is 26081bounded by the region starting from the @code{begin} keyword of the package body 26082and ending at the @code{end} keyword of the package body. 26083 26084@example 26085package body Client is 26086 procedure Proc is 26087 begin 26088 ... 26089 end Proc; 26090begin 26091 Proc; 26092end Client; 26093@end example 26094 26095In the example above, the call to @code{Proc} is an elaboration scenario because 26096it appears within the statement sequence of package body @code{Client}. As a 26097result, the call to @code{Proc} will be invoked when the body of @code{Client} is 26098elaborated. 26099@end itemize 26100 26101@node Elaboration Order,Checking the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT 26102@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{219} 26103@section Elaboration Order 26104 26105 26106The sequence by which the elaboration code of all units within a partition is 26107executed is referred to as @strong{elaboration order}. 26108 26109Within a single unit, elaboration code is executed in sequential order. 26110 26111@quotation 26112 26113@example 26114package body Client is 26115 Result : ... := Server.Func; 26116 26117 procedure Proc is 26118 package Inst is new Server.Gen; 26119 begin 26120 Inst.Eval (Result); 26121 end Proc; 26122begin 26123 Proc; 26124end Client; 26125@end example 26126@end quotation 26127 26128In the example above, the elaboration order within package body @code{Client} is 26129as follows: 26130 26131 26132@enumerate 26133 26134@item 26135The object declaration of @code{Result} is elaborated. 26136 26137 26138@itemize * 26139 26140@item 26141Function @code{Server.Func} is invoked. 26142@end itemize 26143 26144@item 26145The subprogram body of @code{Proc} is elaborated. 26146 26147@item 26148Procedure @code{Proc} is invoked. 26149 26150 26151@itemize * 26152 26153@item 26154Generic unit @code{Server.Gen} is instantiated as @code{Inst}. 26155 26156@item 26157Instance @code{Inst} is elaborated. 26158 26159@item 26160Procedure @code{Inst.Eval} is invoked. 26161@end itemize 26162@end enumerate 26163 26164The elaboration order of all units within a partition depends on the following 26165factors: 26166 26167 26168@itemize * 26169 26170@item 26171@emph{with}ed units 26172 26173@item 26174parent units 26175 26176@item 26177purity of units 26178 26179@item 26180preelaborability of units 26181 26182@item 26183presence of elaboration-control pragmas 26184 26185@item 26186invocations performed in elaboration code 26187@end itemize 26188 26189A program may have several elaboration orders depending on its structure. 26190 26191@quotation 26192 26193@example 26194package Server is 26195 function Func (Index : Integer) return Integer; 26196end Server; 26197@end example 26198 26199@example 26200package body Server is 26201 Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5); 26202 26203 function Func (Index : Integer) return Integer is 26204 begin 26205 return Results (Index); 26206 end Func; 26207end Server; 26208@end example 26209 26210@example 26211with Server; 26212package Client is 26213 Val : constant Integer := Server.Func (3); 26214end Client; 26215@end example 26216 26217@example 26218with Client; 26219procedure Main is begin null; end Main; 26220@end example 26221@end quotation 26222 26223The following elaboration order exhibits a fundamental problem referred to as 26224@emph{access-before-elaboration} or simply @strong{ABE}. 26225 26226@quotation 26227 26228@example 26229spec of Server 26230spec of Client 26231body of Server 26232body of Main 26233@end example 26234@end quotation 26235 26236The elaboration of @code{Server}'s spec materializes function @code{Func}, making it 26237callable. The elaboration of @code{Client}'s spec elaborates the declaration of 26238@code{Val}. This invokes function @code{Server.Func}, however the body of 26239@code{Server.Func} has not been elaborated yet because @code{Server}'s body comes 26240after @code{Client}'s spec in the elaboration order. As a result, the value of 26241constant @code{Val} is now undefined. 26242 26243Without any guarantees from the language, an undetected ABE problem may hinder 26244proper initialization of data, which in turn may lead to undefined behavior at 26245run time. To prevent such ABE problems, Ada employs dynamic checks in the same 26246vein as index or null exclusion checks. A failed ABE check raises exception 26247@code{Program_Error}. 26248 26249The following elaboration order avoids the ABE problem and the program can be 26250successfully elaborated. 26251 26252@quotation 26253 26254@example 26255spec of Server 26256body of Server 26257spec of Client 26258body of Main 26259@end example 26260@end quotation 26261 26262Ada states that a total elaboration order must exist, but it does not define 26263what this order is. A compiler is thus tasked with choosing a suitable 26264elaboration order which satisfies the dependencies imposed by @emph{with} clauses, 26265unit categorization, elaboration-control pragmas, and invocations performed in 26266elaboration code. Ideally an order that avoids ABE problems should be chosen, 26267however a compiler may not always find such an order due to complications with 26268respect to control and data flow. 26269 26270@node Checking the Elaboration Order,Controlling the Elaboration Order in Ada,Elaboration Order,Elaboration Order Handling in GNAT 26271@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{21b} 26272@section Checking the Elaboration Order 26273 26274 26275To avoid placing the entire elaboration-order burden on the programmer, Ada 26276provides three lines of defense: 26277 26278 26279@itemize * 26280 26281@item 26282@emph{Static semantics} 26283 26284Static semantic rules restrict the possible choice of elaboration order. For 26285instance, if unit Client @emph{with}s unit Server, then the spec of Server is 26286always elaborated prior to Client. The same principle applies to child units 26287- the spec of a parent unit is always elaborated prior to the child unit. 26288 26289@item 26290@emph{Dynamic semantics} 26291 26292Dynamic checks are performed at run time, to ensure that a target is 26293elaborated prior to a scenario that invokes it, thus avoiding ABE problems. 26294A failed run-time check raises exception @code{Program_Error}. The following 26295restrictions apply: 26296 26297 26298@itemize - 26299 26300@item 26301@emph{Restrictions on calls} 26302 26303An entry, operator, or subprogram can be called from elaboration code only 26304when the corresponding body has been elaborated. 26305 26306@item 26307@emph{Restrictions on instantiations} 26308 26309A generic unit can be instantiated by elaboration code only when the 26310corresponding body has been elaborated. 26311 26312@item 26313@emph{Restrictions on task activation} 26314 26315A task can be activated by elaboration code only when the body of the 26316associated task type has been elaborated. 26317@end itemize 26318 26319The restrictions above can be summarized by the following rule: 26320 26321@emph{If a target has a body, then this body must be elaborated prior to the 26322scenario that invokes the target.} 26323 26324@item 26325@emph{Elaboration control} 26326 26327Pragmas are provided for the programmer to specify the desired elaboration 26328order. 26329@end itemize 26330 26331@node Controlling the Elaboration Order in Ada,Controlling the Elaboration Order in GNAT,Checking the Elaboration Order,Elaboration Order Handling in GNAT 26332@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21d} 26333@section Controlling the Elaboration Order in Ada 26334 26335 26336Ada provides several idioms and pragmas to aid the programmer with specifying 26337the desired elaboration order and avoiding ABE problems altogether. 26338 26339 26340@itemize * 26341 26342@item 26343@emph{Packages without a body} 26344 26345A library package which does not require a completing body does not suffer 26346from ABE problems. 26347 26348@example 26349package Pack is 26350 generic 26351 type Element is private; 26352 package Containers is 26353 type Element_Array is array (1 .. 10) of Element; 26354 end Containers; 26355end Pack; 26356@end example 26357 26358In the example above, package @code{Pack} does not require a body because it 26359does not contain any constructs which require completion in a body. As a 26360result, generic @code{Pack.Containers} can be instantiated without encountering 26361any ABE problems. 26362@end itemize 26363 26364@geindex pragma Pure 26365 26366 26367@itemize * 26368 26369@item 26370@emph{pragma Pure} 26371 26372Pragma @code{Pure} places sufficient restrictions on a unit to guarantee that no 26373scenario within the unit can result in an ABE problem. 26374@end itemize 26375 26376@geindex pragma Preelaborate 26377 26378 26379@itemize * 26380 26381@item 26382@emph{pragma Preelaborate} 26383 26384Pragma @code{Preelaborate} is slightly less restrictive than pragma @code{Pure}, 26385but still strong enough to prevent ABE problems within a unit. 26386@end itemize 26387 26388@geindex pragma Elaborate_Body 26389 26390 26391@itemize * 26392 26393@item 26394@emph{pragma Elaborate_Body} 26395 26396Pragma @code{Elaborate_Body} requires that the body of a unit is elaborated 26397immediately after its spec. This restriction guarantees that no client 26398scenario can invoke a server target before the target body has been 26399elaborated because the spec and body are effectively "glued" together. 26400 26401@example 26402package Server is 26403 pragma Elaborate_Body; 26404 26405 function Func return Integer; 26406end Server; 26407@end example 26408 26409@example 26410package body Server is 26411 function Func return Integer is 26412 begin 26413 ... 26414 end Func; 26415end Server; 26416@end example 26417 26418@example 26419with Server; 26420package Client is 26421 Val : constant Integer := Server.Func; 26422end Client; 26423@end example 26424 26425In the example above, pragma @code{Elaborate_Body} guarantees the following 26426elaboration order: 26427 26428@example 26429spec of Server 26430body of Server 26431spec of Client 26432@end example 26433 26434because the spec of @code{Server} must be elaborated prior to @code{Client} by 26435virtue of the @emph{with} clause, and in addition the body of @code{Server} must be 26436elaborated immediately after the spec of @code{Server}. 26437 26438Removing pragma @code{Elaborate_Body} could result in the following incorrect 26439elaboration order: 26440 26441@example 26442spec of Server 26443spec of Client 26444body of Server 26445@end example 26446 26447where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} has 26448not been elaborated yet. 26449@end itemize 26450 26451The pragmas outlined above allow a server unit to guarantee safe elaboration 26452use by client units. Thus it is a good rule to mark units as @code{Pure} or 26453@code{Preelaborate}, and if this is not possible, mark them as @code{Elaborate_Body}. 26454 26455There are however situations where @code{Pure}, @code{Preelaborate}, and 26456@code{Elaborate_Body} are not applicable. Ada provides another set of pragmas for 26457use by client units to help ensure the elaboration safety of server units they 26458depend on. 26459 26460@geindex pragma Elaborate (Unit) 26461 26462 26463@itemize * 26464 26465@item 26466@emph{pragma Elaborate (Unit)} 26467 26468Pragma @code{Elaborate} can be placed in the context clauses of a unit, after a 26469@emph{with} clause. It guarantees that both the spec and body of its argument will 26470be elaborated prior to the unit with the pragma. Note that other unrelated 26471units may be elaborated in between the spec and the body. 26472 26473@example 26474package Server is 26475 function Func return Integer; 26476end Server; 26477@end example 26478 26479@example 26480package body Server is 26481 function Func return Integer is 26482 begin 26483 ... 26484 end Func; 26485end Server; 26486@end example 26487 26488@example 26489with Server; 26490pragma Elaborate (Server); 26491package Client is 26492 Val : constant Integer := Server.Func; 26493end Client; 26494@end example 26495 26496In the example above, pragma @code{Elaborate} guarantees the following 26497elaboration order: 26498 26499@example 26500spec of Server 26501body of Server 26502spec of Client 26503@end example 26504 26505Removing pragma @code{Elaborate} could result in the following incorrect 26506elaboration order: 26507 26508@example 26509spec of Server 26510spec of Client 26511body of Server 26512@end example 26513 26514where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} 26515has not been elaborated yet. 26516@end itemize 26517 26518@geindex pragma Elaborate_All (Unit) 26519 26520 26521@itemize * 26522 26523@item 26524@emph{pragma Elaborate_All (Unit)} 26525 26526Pragma @code{Elaborate_All} is placed in the context clauses of a unit, after 26527a @emph{with} clause. It guarantees that both the spec and body of its argument 26528will be elaborated prior to the unit with the pragma, as well as all units 26529@emph{with}ed by the spec and body of the argument, recursively. Note that other 26530unrelated units may be elaborated in between the spec and the body. 26531 26532@example 26533package Math is 26534 function Factorial (Val : Natural) return Natural; 26535end Math; 26536@end example 26537 26538@example 26539package body Math is 26540 function Factorial (Val : Natural) return Natural is 26541 begin 26542 ...; 26543 end Factorial; 26544end Math; 26545@end example 26546 26547@example 26548package Computer is 26549 type Operation_Kind is (None, Op_Factorial); 26550 26551 function Compute 26552 (Val : Natural; 26553 Op : Operation_Kind) return Natural; 26554end Computer; 26555@end example 26556 26557@example 26558with Math; 26559package body Computer is 26560 function Compute 26561 (Val : Natural; 26562 Op : Operation_Kind) return Natural 26563 is 26564 if Op = Op_Factorial then 26565 return Math.Factorial (Val); 26566 end if; 26567 26568 return 0; 26569 end Compute; 26570end Computer; 26571@end example 26572 26573@example 26574with Computer; 26575pragma Elaborate_All (Computer); 26576package Client is 26577 Val : constant Natural := 26578 Computer.Compute (123, Computer.Op_Factorial); 26579end Client; 26580@end example 26581 26582In the example above, pragma @code{Elaborate_All} can result in the following 26583elaboration order: 26584 26585@example 26586spec of Math 26587body of Math 26588spec of Computer 26589body of Computer 26590spec of Client 26591@end example 26592 26593Note that there are several allowable suborders for the specs and bodies of 26594@code{Math} and @code{Computer}, but the point is that these specs and bodies will 26595be elaborated prior to @code{Client}. 26596 26597Removing pragma @code{Elaborate_All} could result in the following incorrect 26598elaboration order: 26599 26600@example 26601spec of Math 26602spec of Computer 26603body of Computer 26604spec of Client 26605body of Math 26606@end example 26607 26608where @code{Client} invokes @code{Computer.Compute}, which in turn invokes 26609@code{Math.Factorial}, but the body of @code{Math.Factorial} has not been 26610elaborated yet. 26611@end itemize 26612 26613All pragmas shown above can be summarized by the following rule: 26614 26615@emph{If a client unit elaborates a server target directly or indirectly, then if 26616the server unit requires a body and does not have pragma Pure, Preelaborate, 26617or Elaborate_Body, then the client unit should have pragma Elaborate or 26618Elaborate_All for the server unit.} 26619 26620If the rule outlined above is not followed, then a program may fall in one of 26621the following states: 26622 26623 26624@itemize * 26625 26626@item 26627@emph{No elaboration order exists} 26628 26629In this case a compiler must diagnose the situation, and refuse to build an 26630executable program. 26631 26632@item 26633@emph{One or more incorrect elaboration orders exist} 26634 26635In this case a compiler can build an executable program, but 26636@code{Program_Error} will be raised when the program is run. 26637 26638@item 26639@emph{Several elaboration orders exist, some correct, some incorrect} 26640 26641In this case the programmer has not controlled the elaboration order. As a 26642result, a compiler may or may not pick one of the correct orders, and the 26643program may or may not raise @code{Program_Error} when it is run. This is the 26644worst possible state because the program may fail on another compiler, or 26645even another version of the same compiler. 26646 26647@item 26648@emph{One or more correct orders exist} 26649 26650In this case a compiler can build an executable program, and the program is 26651run successfully. This state may be guaranteed by following the outlined 26652rules, or may be the result of good program architecture. 26653@end itemize 26654 26655Note that one additional advantage of using @code{Elaborate} and @code{Elaborate_All} 26656is that the program continues to stay in the last state (one or more correct 26657orders exist) even if maintenance changes the bodies of targets. 26658 26659@node Controlling the Elaboration Order in GNAT,Mixing Elaboration Models,Controlling the Elaboration Order in Ada,Elaboration Order Handling in GNAT 26660@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{21e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{21f} 26661@section Controlling the Elaboration Order in GNAT 26662 26663 26664In addition to Ada semantics and rules synthesized from them, GNAT offers 26665three elaboration models to aid the programmer with specifying the correct 26666elaboration order and to diagnose elaboration problems. 26667 26668@geindex Dynamic elaboration model 26669 26670 26671@itemize * 26672 26673@item 26674@emph{Dynamic elaboration model} 26675 26676This is the most permissive of the three elaboration models and emulates the 26677behavior specified by the Ada Reference Manual. When the dynamic model is in 26678effect, GNAT makes the following assumptions: 26679 26680 26681@itemize - 26682 26683@item 26684All code within all units in a partition is considered to be elaboration 26685code. 26686 26687@item 26688Some of the invocations in elaboration code may not take place at run time 26689due to conditional execution. 26690@end itemize 26691 26692GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios 26693that invoke internal targets. In addition, GNAT generates run-time checks for 26694all external targets and for all scenarios that may exhibit ABE problems. 26695 26696The elaboration order is obtained by honoring all @emph{with} clauses, purity and 26697preelaborability of units, and elaboration-control pragmas. The dynamic model 26698attempts to take all invocations in elaboration code into account. If an 26699invocation leads to a circularity, GNAT ignores the invocation based on the 26700assumptions stated above. An order obtained using the dynamic model may fail 26701an ABE check at run time when GNAT ignored an invocation. 26702 26703The dynamic model is enabled with compiler switch @code{-gnatE}. 26704@end itemize 26705 26706@geindex Static elaboration model 26707 26708 26709@itemize * 26710 26711@item 26712@emph{Static elaboration model} 26713 26714This is the middle ground of the three models. When the static model is in 26715effect, GNAT makes the following assumptions: 26716 26717 26718@itemize - 26719 26720@item 26721Only code at the library level and in package body statements within all 26722units in a partition is considered to be elaboration code. 26723 26724@item 26725All invocations in elaboration will take place at run time, regardless of 26726conditional execution. 26727@end itemize 26728 26729GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios 26730that invoke internal targets. In addition, GNAT generates run-time checks for 26731all external targets and for all scenarios that may exhibit ABE problems. 26732 26733The elaboration order is obtained by honoring all @emph{with} clauses, purity and 26734preelaborability of units, presence of elaboration-control pragmas, and all 26735invocations in elaboration code. An order obtained using the static model is 26736guaranteed to be ABE problem-free, excluding dispatching calls and 26737access-to-subprogram types. 26738 26739The static model is the default model in GNAT. 26740@end itemize 26741 26742@geindex SPARK elaboration model 26743 26744 26745@itemize * 26746 26747@item 26748@emph{SPARK elaboration model} 26749 26750This is the most conservative of the three models and enforces the SPARK 26751rules of elaboration as defined in the SPARK Reference Manual, section 7.7. 26752The SPARK model is in effect only when a scenario and a target reside in a 26753region subject to @code{SPARK_Mode On}, otherwise the dynamic or static model 26754is in effect. 26755 26756The SPARK model is enabled with compiler switch @code{-gnatd.v}. 26757@end itemize 26758 26759@geindex Legacy elaboration models 26760 26761 26762@itemize * 26763 26764@item 26765@emph{Legacy elaboration models} 26766 26767In addition to the three elaboration models outlined above, GNAT provides the 26768following legacy models: 26769 26770 26771@itemize - 26772 26773@item 26774@cite{Legacy elaboration-checking model} available in pre-18.x versions of GNAT. 26775This model is enabled with compiler switch @code{-gnatH}. 26776 26777@item 26778@cite{Legacy elaboration-order model} available in pre-20.x versions of GNAT. 26779This model is enabled with binder switch @code{-H}. 26780@end itemize 26781@end itemize 26782 26783@geindex Relaxed elaboration mode 26784 26785The dynamic, legacy, and static models can be relaxed using compiler switch 26786@code{-gnatJ}, making them more permissive. Note that in this mode, GNAT 26787may not diagnose certain elaboration issues or install run-time checks. 26788 26789@node Mixing Elaboration Models,ABE Diagnostics,Controlling the Elaboration Order in GNAT,Elaboration Order Handling in GNAT 26790@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{220}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{221} 26791@section Mixing Elaboration Models 26792 26793 26794It is possible to mix units compiled with a different elaboration model, 26795however the following rules must be observed: 26796 26797 26798@itemize * 26799 26800@item 26801A client unit compiled with the dynamic model can only @emph{with} a server unit 26802that meets at least one of the following criteria: 26803 26804 26805@itemize - 26806 26807@item 26808The server unit is compiled with the dynamic model. 26809 26810@item 26811The server unit is a GNAT implementation unit from the @code{Ada}, @code{GNAT}, 26812@code{Interfaces}, or @code{System} hierarchies. 26813 26814@item 26815The server unit has pragma @code{Pure} or @code{Preelaborate}. 26816 26817@item 26818The client unit has an explicit @code{Elaborate_All} pragma for the server 26819unit. 26820@end itemize 26821@end itemize 26822 26823These rules ensure that elaboration checks are not omitted. If the rules are 26824violated, the binder emits a warning: 26825 26826@quotation 26827 26828@example 26829warning: "x.ads" has dynamic elaboration checks and with's 26830warning: "y.ads" which has static elaboration checks 26831@end example 26832@end quotation 26833 26834The warnings can be suppressed by binder switch @code{-ws}. 26835 26836@node ABE Diagnostics,SPARK Diagnostics,Mixing Elaboration Models,Elaboration Order Handling in GNAT 26837@anchor{gnat_ugn/elaboration_order_handling_in_gnat abe-diagnostics}@anchor{222}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{223} 26838@section ABE Diagnostics 26839 26840 26841GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios 26842that invoke internal targets, regardless of whether the dynamic, SPARK, or 26843static model is in effect. 26844 26845Note that GNAT emits warnings rather than hard errors whenever it encounters an 26846elaboration problem. This is because the elaboration model in effect may be too 26847conservative, or a particular scenario may not be invoked due conditional 26848execution. The warnings can be suppressed selectively with @code{pragma Warnings 26849(Off)} or globally with compiler switch @code{-gnatwL}. 26850 26851A @emph{guaranteed ABE} arises when the body of a target is not elaborated early 26852enough, and causes @emph{all} scenarios that directly invoke the target to fail. 26853 26854@quotation 26855 26856@example 26857package body Guaranteed_ABE is 26858 function ABE return Integer; 26859 26860 Val : constant Integer := ABE; 26861 26862 function ABE return Integer is 26863 begin 26864 ... 26865 end ABE; 26866end Guaranteed_ABE; 26867@end example 26868@end quotation 26869 26870In the example above, the elaboration of @code{Guaranteed_ABE}'s body elaborates 26871the declaration of @code{Val}. This invokes function @code{ABE}, however the body of 26872@code{ABE} has not been elaborated yet. GNAT emits the following diagnostic: 26873 26874@quotation 26875 26876@example 268774. Val : constant Integer := ABE; 26878 | 26879 >>> warning: cannot call "ABE" before body seen 26880 >>> warning: Program_Error will be raised at run time 26881@end example 26882@end quotation 26883 26884A @emph{conditional ABE} arises when the body of a target is not elaborated early 26885enough, and causes @emph{some} scenarios that directly invoke the target to fail. 26886 26887@quotation 26888 26889@example 26890 1. package body Conditional_ABE is 26891 2. procedure Force_Body is null; 26892 3. 26893 4. generic 26894 5. with function Func return Integer; 26895 6. package Gen is 26896 7. Val : constant Integer := Func; 26897 8. end Gen; 26898 9. 2689910. function ABE return Integer; 2690011. 2690112. function Cause_ABE return Boolean is 2690213. package Inst is new Gen (ABE); 2690314. begin 2690415. ... 2690516. end Cause_ABE; 2690617. 2690718. Val : constant Boolean := Cause_ABE; 2690819. 2690920. function ABE return Integer is 2691021. begin 2691122. ... 2691223. end ABE; 2691324. 2691425. Safe : constant Boolean := Cause_ABE; 2691526. end Conditional_ABE; 26916@end example 26917@end quotation 26918 26919In the example above, the elaboration of package body @code{Conditional_ABE} 26920elaborates the declaration of @code{Val}. This invokes function @code{Cause_ABE}, 26921which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of 26922@code{Inst} invokes function @code{ABE}, however the body of @code{ABE} has not been 26923elaborated yet. GNAT emits the following diagnostic: 26924 26925@quotation 26926 26927@example 2692813. package Inst is new Gen (ABE); 26929 | 26930 >>> warning: in instantiation at line 7 26931 >>> warning: cannot call "ABE" before body seen 26932 >>> warning: Program_Error may be raised at run time 26933 >>> warning: body of unit "Conditional_ABE" elaborated 26934 >>> warning: function "Cause_ABE" called at line 18 26935 >>> warning: function "ABE" called at line 7, instance at line 13 26936@end example 26937@end quotation 26938 26939Note that the same ABE problem does not occur with the elaboration of 26940declaration @code{Safe} because the body of function @code{ABE} has already been 26941elaborated at that point. 26942 26943@node SPARK Diagnostics,Elaboration Circularities,ABE Diagnostics,Elaboration Order Handling in GNAT 26944@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{224}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{225} 26945@section SPARK Diagnostics 26946 26947 26948GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference 26949Manual section 7.7 when compiler switch @code{-gnatd.v} is in effect. Note 26950that GNAT emits hard errors whenever it encounters a violation of the SPARK 26951rules. 26952 26953@quotation 26954 26955@example 269561. with Server; 269572. package body SPARK_Diagnostics with SPARK_Mode is 269583. Val : constant Integer := Server.Func; 26959 | 26960 >>> call to "Func" during elaboration in SPARK 26961 >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server" 26962 >>> body of unit "SPARK_Model" elaborated 26963 >>> function "Func" called at line 3 26964 269654. end SPARK_Diagnostics; 26966@end example 26967@end quotation 26968 26969@node Elaboration Circularities,Resolving Elaboration Circularities,SPARK Diagnostics,Elaboration Order Handling in GNAT 26970@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{226}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{227} 26971@section Elaboration Circularities 26972 26973 26974An @strong{elaboration circularity} occurs whenever the elaboration of a set of 26975units enters a deadlocked state, where each unit is waiting for another unit 26976to be elaborated. This situation may be the result of improper use of @emph{with} 26977clauses, elaboration-control pragmas, or invocations in elaboration code. 26978 26979The following example exhibits an elaboration circularity. 26980 26981@quotation 26982 26983@example 26984with B; pragma Elaborate (B); 26985package A is 26986end A; 26987@end example 26988 26989@example 26990package B is 26991 procedure Force_Body; 26992end B; 26993@end example 26994 26995@example 26996with C; 26997package body B is 26998 procedure Force_Body is null; 26999 27000 Elab : constant Integer := C.Func; 27001end B; 27002@end example 27003 27004@example 27005package C is 27006 function Func return Integer; 27007end C; 27008@end example 27009 27010@example 27011with A; 27012package body C is 27013 function Func return Integer is 27014 begin 27015 ... 27016 end Func; 27017end C; 27018@end example 27019@end quotation 27020 27021The binder emits the following diagnostic: 27022 27023@quotation 27024 27025@example 27026error: Elaboration circularity detected 27027info: 27028info: Reason: 27029info: 27030info: unit "a (spec)" depends on its own elaboration 27031info: 27032info: Circularity: 27033info: 27034info: unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)" 27035info: unit "b (body)" is in the closure of pragma Elaborate 27036info: unit "b (body)" invokes a construct of unit "c (body)" at elaboration time 27037info: unit "c (body)" has with clause for unit "a (spec)" 27038info: 27039info: Suggestions: 27040info: 27041info: remove pragma Elaborate for unit "b (body)" in unit "a (spec)" 27042info: use the dynamic elaboration model (compiler switch -gnatE) 27043@end example 27044@end quotation 27045 27046The diagnostic consist of the following sections: 27047 27048 27049@itemize * 27050 27051@item 27052Reason 27053 27054This section provides a short explanation describing why the set of units 27055could not be ordered. 27056 27057@item 27058Circularity 27059 27060This section enumerates the units comprising the deadlocked set, along with 27061their interdependencies. 27062 27063@item 27064Suggestions 27065 27066This section enumerates various tactics for eliminating the circularity. 27067@end itemize 27068 27069@node Resolving Elaboration Circularities,Elaboration-related Compiler Switches,Elaboration Circularities,Elaboration Order Handling in GNAT 27070@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{228}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{229} 27071@section Resolving Elaboration Circularities 27072 27073 27074The most desirable option from the point of view of long-term maintenance is to 27075rearrange the program so that the elaboration problems are avoided. One useful 27076technique is to place the elaboration code into separate child packages. 27077Another is to move some of the initialization code to explicitly invoked 27078subprograms, where the program controls the order of initialization explicitly. 27079Although this is the most desirable option, it may be impractical and involve 27080too much modification, especially in the case of complex legacy code. 27081 27082When faced with an elaboration circularity, the programmer should also consider 27083the tactics given in the suggestions section of the circularity diagnostic. 27084Depending on the units involved in the circularity, their @emph{with} clauses, 27085purity, preelaborability, presence of elaboration-control pragmas and 27086invocations at elaboration time, the binder may suggest one or more of the 27087following tactics to eliminate the circularity: 27088 27089 27090@itemize * 27091 27092@item 27093Pragma Elaborate elimination 27094 27095@example 27096remove pragma Elaborate for unit "..." in unit "..." 27097@end example 27098 27099This tactic is suggested when the binder has determined that pragma 27100@code{Elaborate}: 27101 27102 27103@itemize - 27104 27105@item 27106Prevents a set of units from being elaborated. 27107 27108@item 27109The removal of the pragma will not eliminate the semantic effects of the 27110pragma. In other words, the argument of the pragma will still be elaborated 27111prior to the unit containing the pragma. 27112 27113@item 27114The removal of the pragma will enable the successful ordering of the units. 27115@end itemize 27116 27117The programmer should remove the pragma as advised, and rebuild the program. 27118 27119@item 27120Pragma Elaborate_All elimination 27121 27122@example 27123remove pragma Elaborate_All for unit "..." in unit "..." 27124@end example 27125 27126This tactic is suggested when the binder has determined that pragma 27127@code{Elaborate_All}: 27128 27129 27130@itemize - 27131 27132@item 27133Prevents a set of units from being elaborated. 27134 27135@item 27136The removal of the pragma will not eliminate the semantic effects of the 27137pragma. In other words, the argument of the pragma along with its @emph{with} 27138closure will still be elaborated prior to the unit containing the pragma. 27139 27140@item 27141The removal of the pragma will enable the successful ordering of the units. 27142@end itemize 27143 27144The programmer should remove the pragma as advised, and rebuild the program. 27145 27146@item 27147Pragma Elaborate_All downgrade 27148 27149@example 27150change pragma Elaborate_All for unit "..." to Elaborate in unit "..." 27151@end example 27152 27153This tactic is always suggested with the pragma @code{Elaborate_All} elimination 27154tactic. It offers a different alernative of guaranteeing that the argument of 27155the pragma will still be elaborated prior to the unit containing the pragma. 27156 27157The programmer should update the pragma as advised, and rebuild the program. 27158 27159@item 27160Pragma Elaborate_Body elimination 27161 27162@example 27163remove pragma Elaborate_Body in unit "..." 27164@end example 27165 27166This tactic is suggested when the binder has determined that pragma 27167@code{Elaborate_Body}: 27168 27169 27170@itemize - 27171 27172@item 27173Prevents a set of units from being elaborated. 27174 27175@item 27176The removal of the pragma will enable the successful ordering of the units. 27177@end itemize 27178 27179Note that the binder cannot determine whether the pragma is required for 27180other purposes, such as guaranteeing the initialization of a variable 27181declared in the spec by elaboration code in the body. 27182 27183The programmer should remove the pragma as advised, and rebuild the program. 27184 27185@item 27186Use of pragma Restrictions 27187 27188@example 27189use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code) 27190@end example 27191 27192This tactic is suggested when the binder has determined that a task 27193activation at elaboration time: 27194 27195 27196@itemize - 27197 27198@item 27199Prevents a set of units from being elaborated. 27200@end itemize 27201 27202Note that the binder cannot determine with certainty whether the task will 27203block at elaboration time. 27204 27205The programmer should create a configuration file, place the pragma within, 27206update the general compilation arguments, and rebuild the program. 27207 27208@item 27209Use of dynamic elaboration model 27210 27211@example 27212use the dynamic elaboration model (compiler switch -gnatE) 27213@end example 27214 27215This tactic is suggested when the binder has determined that an invocation at 27216elaboration time: 27217 27218 27219@itemize - 27220 27221@item 27222Prevents a set of units from being elaborated. 27223 27224@item 27225The use of the dynamic model will enable the successful ordering of the 27226units. 27227@end itemize 27228 27229The programmer has two options: 27230 27231 27232@itemize - 27233 27234@item 27235Determine the units involved in the invocation using the detailed 27236invocation information, and add compiler switch @code{-gnatE} to the 27237compilation arguments of selected files only. This approach will yield 27238safer elaboration orders compared to the other option because it will 27239minimize the opportunities presented to the dynamic model for ignoring 27240invocations. 27241 27242@item 27243Add compiler switch @code{-gnatE} to the general compilation arguments. 27244@end itemize 27245 27246@item 27247Use of detailed invocation information 27248 27249@example 27250use detailed invocation information (compiler switch -gnatd_F) 27251@end example 27252 27253This tactic is always suggested with the use of the dynamic model tactic. It 27254causes the circularity section of the circularity diagnostic to describe the 27255flow of elaboration code from a unit to a unit, enumerating all such paths in 27256the process. 27257 27258The programmer should analyze this information to determine which units 27259should be compiled with the dynamic model. 27260 27261@item 27262Forced-dependency elimination 27263 27264@example 27265remove the dependency of unit "..." on unit "..." from the argument of switch -f 27266@end example 27267 27268This tactic is suggested when the binder has determined that a dependency 27269present in the forced-elaboration-order file indicated by binder switch 27270@code{-f}: 27271 27272 27273@itemize - 27274 27275@item 27276Prevents a set of units from being elaborated. 27277 27278@item 27279The removal of the dependency will enable the successful ordering of the 27280units. 27281@end itemize 27282 27283The programmer should edit the forced-elaboration-order file, remove the 27284dependency, and rebind the program. 27285 27286@item 27287All forced-dependency elimination 27288 27289@example 27290remove switch -f 27291@end example 27292 27293This tactic is suggested in case editing the forced-elaboration-order file is 27294not an option. 27295 27296The programmer should remove binder switch @code{-f} from the binder 27297arguments, and rebind. 27298 27299@item 27300Multiple-circularities diagnostic 27301 27302@example 27303diagnose all circularities (binder switch -d_C) 27304@end example 27305 27306By default, the binder will diagnose only the highest-precedence circularity. 27307If the program contains multiple circularities, the binder will suggest the 27308use of binder switch @code{-d_C} in order to obtain the diagnostics of all 27309circularities. 27310 27311The programmer should add binder switch @code{-d_C} to the binder 27312arguments, and rebind. 27313@end itemize 27314 27315If none of the tactics suggested by the binder eliminate the elaboration 27316circularity, the programmer should consider using one of the legacy elaboration 27317models, in the following order: 27318 27319 27320@itemize * 27321 27322@item 27323Use the pre-20.x legacy elaboration-order model, with binder switch 27324@code{-H}. 27325 27326@item 27327Use both pre-18.x and pre-20.x legacy elaboration models, with compiler 27328switch @code{-gnatH} and binder switch @code{-H}. 27329 27330@item 27331Use the relaxed static-elaboration model, with compiler switches 27332@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}. 27333 27334@item 27335Use the relaxed dynamic-elaboration model, with compiler switches 27336@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch 27337@code{-H}. 27338@end itemize 27339 27340@node Elaboration-related Compiler Switches,Summary of Procedures for Elaboration Control,Resolving Elaboration Circularities,Elaboration Order Handling in GNAT 27341@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{22b} 27342@section Elaboration-related Compiler Switches 27343 27344 27345GNAT has several switches that affect the elaboration model and consequently 27346the elaboration order chosen by the binder. 27347 27348@geindex -gnatE (gnat) 27349 27350 27351@table @asis 27352 27353@item @code{-gnatE} 27354 27355Dynamic elaboration checking mode enabled 27356 27357When this switch is in effect, GNAT activates the dynamic model. 27358@end table 27359 27360@geindex -gnatel (gnat) 27361 27362 27363@table @asis 27364 27365@item @code{-gnatel} 27366 27367Turn on info messages on generated Elaborate[_All] pragmas 27368 27369This switch is only applicable to the pre-20.x legacy elaboration models. 27370The post-20.x elaboration model no longer relies on implicitly generated 27371@code{Elaborate} and @code{Elaborate_All} pragmas to order units. 27372 27373When this switch is in effect, GNAT will emit the following supplementary 27374information depending on the elaboration model in effect. 27375 27376 27377@itemize - 27378 27379@item 27380@emph{Dynamic model} 27381 27382GNAT will indicate missing @code{Elaborate} and @code{Elaborate_All} pragmas for 27383all library-level scenarios within the partition. 27384 27385@item 27386@emph{Static model} 27387 27388GNAT will indicate all scenarios invoked during elaboration. In addition, 27389it will provide detailed traceback when an implicit @code{Elaborate} or 27390@code{Elaborate_All} pragma is generated. 27391 27392@item 27393@emph{SPARK model} 27394 27395GNAT will indicate how an elaboration requirement is met by the context of 27396a unit. This diagnostic requires compiler switch @code{-gnatd.v}. 27397 27398@example 273991. with Server; pragma Elaborate_All (Server); 274002. package Client with SPARK_Mode is 274013. Val : constant Integer := Server.Func; 27402 | 27403 >>> info: call to "Func" during elaboration in SPARK 27404 >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1 27405 274064. end Client; 27407@end example 27408@end itemize 27409@end table 27410 27411@geindex -gnatH (gnat) 27412 27413 27414@table @asis 27415 27416@item @code{-gnatH} 27417 27418Legacy elaboration checking mode enabled 27419 27420When this switch is in effect, GNAT will utilize the pre-18.x elaboration 27421model. 27422@end table 27423 27424@geindex -gnatJ (gnat) 27425 27426 27427@table @asis 27428 27429@item @code{-gnatJ} 27430 27431Relaxed elaboration checking mode enabled 27432 27433When this switch is in effect, GNAT will not process certain scenarios, 27434resulting in a more permissive elaboration model. Note that this may 27435eliminate some diagnostics and run-time checks. 27436@end table 27437 27438@geindex -gnatw.f (gnat) 27439 27440 27441@table @asis 27442 27443@item @code{-gnatw.f} 27444 27445Turn on warnings for suspicious Subp'Access 27446 27447When this switch is in effect, GNAT will treat @code{'Access} of an entry, 27448operator, or subprogram as a potential call to the target and issue warnings: 27449 27450@example 27451 1. package body Attribute_Call is 27452 2. function Func return Integer; 27453 3. type Func_Ptr is access function return Integer; 27454 4. 27455 5. Ptr : constant Func_Ptr := Func'Access; 27456 | 27457 >>> warning: "Access" attribute of "Func" before body seen 27458 >>> warning: possible Program_Error on later references 27459 >>> warning: body of unit "Attribute_Call" elaborated 27460 >>> warning: "Access" of "Func" taken at line 5 27461 27462 6. 27463 7. function Func return Integer is 27464 8. begin 27465 9. ... 2746610. end Func; 2746711. end Attribute_Call; 27468@end example 27469 27470In the example above, the elaboration of declaration @code{Ptr} is assigned 27471@code{Func'Access} before the body of @code{Func} has been elaborated. 27472@end table 27473 27474@geindex -gnatwl (gnat) 27475 27476 27477@table @asis 27478 27479@item @code{-gnatwl} 27480 27481Turn on warnings for elaboration problems 27482 27483When this switch is in effect, GNAT emits diagnostics in the form of warnings 27484concerning various elaboration problems. The warnings are enabled by default. 27485The switch is provided in case all warnings are suppressed, but elaboration 27486warnings are still desired. 27487 27488@item @code{-gnatwL} 27489 27490Turn off warnings for elaboration problems 27491 27492When this switch is in effect, GNAT no longer emits any diagnostics in the 27493form of warnings. Selective suppression of elaboration problems is possible 27494using @code{pragma Warnings (Off)}. 27495 27496@example 27497 1. package body Selective_Suppression is 27498 2. function ABE return Integer; 27499 3. 27500 4. Val_1 : constant Integer := ABE; 27501 | 27502 >>> warning: cannot call "ABE" before body seen 27503 >>> warning: Program_Error will be raised at run time 27504 27505 5. 27506 6. pragma Warnings (Off); 27507 7. Val_2 : constant Integer := ABE; 27508 8. pragma Warnings (On); 27509 9. 2751010. function ABE return Integer is 2751111. begin 2751212. ... 2751313. end ABE; 2751414. end Selective_Suppression; 27515@end example 27516 27517Note that suppressing elaboration warnings does not eliminate run-time 27518checks. The example above will still fail at run time with an ABE. 27519@end table 27520 27521@node Summary of Procedures for Elaboration Control,Inspecting the Chosen Elaboration Order,Elaboration-related Compiler Switches,Elaboration Order Handling in GNAT 27522@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{22d} 27523@section Summary of Procedures for Elaboration Control 27524 27525 27526A programmer should first compile the program with the default options, using 27527none of the binder or compiler switches. If the binder succeeds in finding an 27528elaboration order, then apart from possible cases involing dispatching calls 27529and access-to-subprogram types, the program is free of elaboration errors. 27530 27531If it is important for the program to be portable to compilers other than GNAT, 27532then the programmer should use compiler switch @code{-gnatel} and consider 27533the messages about missing or implicitly created @code{Elaborate} and 27534@code{Elaborate_All} pragmas. 27535 27536If the binder reports an elaboration circularity, the programmer has several 27537options: 27538 27539 27540@itemize * 27541 27542@item 27543Ensure that elaboration warnings are enabled. This will allow the static 27544model to output trace information of elaboration issues. The trace 27545information could shed light on previously unforeseen dependencies, as well 27546as their origins. Elaboration warnings are enabled with compiler switch 27547@code{-gnatwl}. 27548 27549@item 27550Cosider the tactics given in the suggestions section of the circularity 27551diagnostic. 27552 27553@item 27554If none of the steps outlined above resolve the circularity, use a more 27555permissive elaboration model, in the following order: 27556 27557 27558@itemize - 27559 27560@item 27561Use the pre-20.x legacy elaboration-order model, with binder switch 27562@code{-H}. 27563 27564@item 27565Use both pre-18.x and pre-20.x legacy elaboration models, with compiler 27566switch @code{-gnatH} and binder switch @code{-H}. 27567 27568@item 27569Use the relaxed static elaboration model, with compiler switches 27570@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}. 27571 27572@item 27573Use the relaxed dynamic elaboration model, with compiler switches 27574@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch 27575@code{-H}. 27576@end itemize 27577@end itemize 27578 27579@node Inspecting the Chosen Elaboration Order,,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT 27580@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{22f} 27581@section Inspecting the Chosen Elaboration Order 27582 27583 27584To see the elaboration order chosen by the binder, inspect the contents of file 27585@cite{b~xxx.adb}. On certain targets, this file appears as @cite{b_xxx.adb}. The 27586elaboration order appears as a sequence of calls to @code{Elab_Body} and 27587@code{Elab_Spec}, interspersed with assignments to @cite{Exxx} which indicates that a 27588particular unit is elaborated. For example: 27589 27590@quotation 27591 27592@example 27593System.Soft_Links'Elab_Body; 27594E14 := True; 27595System.Secondary_Stack'Elab_Body; 27596E18 := True; 27597System.Exception_Table'Elab_Body; 27598E24 := True; 27599Ada.Io_Exceptions'Elab_Spec; 27600E67 := True; 27601Ada.Tags'Elab_Spec; 27602Ada.Streams'Elab_Spec; 27603E43 := True; 27604Interfaces.C'Elab_Spec; 27605E69 := True; 27606System.Finalization_Root'Elab_Spec; 27607E60 := True; 27608System.Os_Lib'Elab_Body; 27609E71 := True; 27610System.Finalization_Implementation'Elab_Spec; 27611System.Finalization_Implementation'Elab_Body; 27612E62 := True; 27613Ada.Finalization'Elab_Spec; 27614E58 := True; 27615Ada.Finalization.List_Controller'Elab_Spec; 27616E76 := True; 27617System.File_Control_Block'Elab_Spec; 27618E74 := True; 27619System.File_Io'Elab_Body; 27620E56 := True; 27621Ada.Tags'Elab_Body; 27622E45 := True; 27623Ada.Text_Io'Elab_Spec; 27624Ada.Text_Io'Elab_Body; 27625E07 := True; 27626@end example 27627@end quotation 27628 27629Note also binder switch @code{-l}, which outputs the chosen elaboration 27630order and provides a more readable form of the above: 27631 27632@quotation 27633 27634@example 27635ada (spec) 27636interfaces (spec) 27637system (spec) 27638system.case_util (spec) 27639system.case_util (body) 27640system.concat_2 (spec) 27641system.concat_2 (body) 27642system.concat_3 (spec) 27643system.concat_3 (body) 27644system.htable (spec) 27645system.parameters (spec) 27646system.parameters (body) 27647system.crtl (spec) 27648interfaces.c_streams (spec) 27649interfaces.c_streams (body) 27650system.restrictions (spec) 27651system.restrictions (body) 27652system.standard_library (spec) 27653system.exceptions (spec) 27654system.exceptions (body) 27655system.storage_elements (spec) 27656system.storage_elements (body) 27657system.secondary_stack (spec) 27658system.stack_checking (spec) 27659system.stack_checking (body) 27660system.string_hash (spec) 27661system.string_hash (body) 27662system.htable (body) 27663system.strings (spec) 27664system.strings (body) 27665system.traceback (spec) 27666system.traceback (body) 27667system.traceback_entries (spec) 27668system.traceback_entries (body) 27669ada.exceptions (spec) 27670ada.exceptions.last_chance_handler (spec) 27671system.soft_links (spec) 27672system.soft_links (body) 27673ada.exceptions.last_chance_handler (body) 27674system.secondary_stack (body) 27675system.exception_table (spec) 27676system.exception_table (body) 27677ada.io_exceptions (spec) 27678ada.tags (spec) 27679ada.streams (spec) 27680interfaces.c (spec) 27681interfaces.c (body) 27682system.finalization_root (spec) 27683system.finalization_root (body) 27684system.memory (spec) 27685system.memory (body) 27686system.standard_library (body) 27687system.os_lib (spec) 27688system.os_lib (body) 27689system.unsigned_types (spec) 27690system.stream_attributes (spec) 27691system.stream_attributes (body) 27692system.finalization_implementation (spec) 27693system.finalization_implementation (body) 27694ada.finalization (spec) 27695ada.finalization (body) 27696ada.finalization.list_controller (spec) 27697ada.finalization.list_controller (body) 27698system.file_control_block (spec) 27699system.file_io (spec) 27700system.file_io (body) 27701system.val_uns (spec) 27702system.val_util (spec) 27703system.val_util (body) 27704system.val_uns (body) 27705system.wch_con (spec) 27706system.wch_con (body) 27707system.wch_cnv (spec) 27708system.wch_jis (spec) 27709system.wch_jis (body) 27710system.wch_cnv (body) 27711system.wch_stw (spec) 27712system.wch_stw (body) 27713ada.tags (body) 27714ada.exceptions (body) 27715ada.text_io (spec) 27716ada.text_io (body) 27717text_io (spec) 27718gdbstr (body) 27719@end example 27720@end quotation 27721 27722@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top 27723@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{230}@anchor{gnat_ugn/inline_assembler id1}@anchor{231} 27724@chapter Inline Assembler 27725 27726 27727@geindex Inline Assembler 27728 27729If you need to write low-level software that interacts directly 27730with the hardware, Ada provides two ways to incorporate assembly 27731language code into your program. First, you can import and invoke 27732external routines written in assembly language, an Ada feature fully 27733supported by GNAT. However, for small sections of code it may be simpler 27734or more efficient to include assembly language statements directly 27735in your Ada source program, using the facilities of the implementation-defined 27736package @code{System.Machine_Code}, which incorporates the gcc 27737Inline Assembler. The Inline Assembler approach offers a number of advantages, 27738including the following: 27739 27740 27741@itemize * 27742 27743@item 27744No need to use non-Ada tools 27745 27746@item 27747Consistent interface over different targets 27748 27749@item 27750Automatic usage of the proper calling conventions 27751 27752@item 27753Access to Ada constants and variables 27754 27755@item 27756Definition of intrinsic routines 27757 27758@item 27759Possibility of inlining a subprogram comprising assembler code 27760 27761@item 27762Code optimizer can take Inline Assembler code into account 27763@end itemize 27764 27765This appendix presents a series of examples to show you how to use 27766the Inline Assembler. Although it focuses on the Intel x86, 27767the general approach applies also to other processors. 27768It is assumed that you are familiar with Ada 27769and with assembly language programming. 27770 27771@menu 27772* Basic Assembler Syntax:: 27773* A Simple Example of Inline Assembler:: 27774* Output Variables in Inline Assembler:: 27775* Input Variables in Inline Assembler:: 27776* Inlining Inline Assembler Code:: 27777* Other Asm Functionality:: 27778 27779@end menu 27780 27781@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler 27782@anchor{gnat_ugn/inline_assembler id2}@anchor{232}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{233} 27783@section Basic Assembler Syntax 27784 27785 27786The assembler used by GNAT and gcc is based not on the Intel assembly 27787language, but rather on a language that descends from the AT&T Unix 27788assembler @code{as} (and which is often referred to as 'AT&T syntax'). 27789The following table summarizes the main features of @code{as} syntax 27790and points out the differences from the Intel conventions. 27791See the gcc @code{as} and @code{gas} (an @code{as} macro 27792pre-processor) documentation for further information. 27793 27794 27795@display 27796@emph{Register names}@w{ } 27797@display 27798gcc / @code{as}: Prefix with '%'; for example @code{%eax}@w{ } 27799Intel: No extra punctuation; for example @code{eax}@w{ } 27800@end display 27801@end display 27802 27803 27804 27805 27806@display 27807@emph{Immediate operand}@w{ } 27808@display 27809gcc / @code{as}: Prefix with '$'; for example @code{$4}@w{ } 27810Intel: No extra punctuation; for example @code{4}@w{ } 27811@end display 27812@end display 27813 27814 27815 27816 27817@display 27818@emph{Address}@w{ } 27819@display 27820gcc / @code{as}: Prefix with '$'; for example @code{$loc}@w{ } 27821Intel: No extra punctuation; for example @code{loc}@w{ } 27822@end display 27823@end display 27824 27825 27826 27827 27828@display 27829@emph{Memory contents}@w{ } 27830@display 27831gcc / @code{as}: No extra punctuation; for example @code{loc}@w{ } 27832Intel: Square brackets; for example @code{[loc]}@w{ } 27833@end display 27834@end display 27835 27836 27837 27838 27839@display 27840@emph{Register contents}@w{ } 27841@display 27842gcc / @code{as}: Parentheses; for example @code{(%eax)}@w{ } 27843Intel: Square brackets; for example @code{[eax]}@w{ } 27844@end display 27845@end display 27846 27847 27848 27849 27850@display 27851@emph{Hexadecimal numbers}@w{ } 27852@display 27853gcc / @code{as}: Leading '0x' (C language syntax); for example @code{0xA0}@w{ } 27854Intel: Trailing 'h'; for example @code{A0h}@w{ } 27855@end display 27856@end display 27857 27858 27859 27860 27861@display 27862@emph{Operand size}@w{ } 27863@display 27864gcc / @code{as}: Explicit in op code; for example @code{movw} to move a 16-bit word@w{ } 27865Intel: Implicit, deduced by assembler; for example @code{mov}@w{ } 27866@end display 27867@end display 27868 27869 27870 27871 27872@display 27873@emph{Instruction repetition}@w{ } 27874@display 27875gcc / @code{as}: Split into two lines; for example@w{ } 27876@display 27877@code{rep}@w{ } 27878@code{stosl}@w{ } 27879@end display 27880Intel: Keep on one line; for example @code{rep stosl}@w{ } 27881@end display 27882@end display 27883 27884 27885 27886 27887@display 27888@emph{Order of operands}@w{ } 27889@display 27890gcc / @code{as}: Source first; for example @code{movw $4, %eax}@w{ } 27891Intel: Destination first; for example @code{mov eax, 4}@w{ } 27892@end display 27893@end display 27894 27895 27896 27897@node A Simple Example of Inline Assembler,Output Variables in Inline Assembler,Basic Assembler Syntax,Inline Assembler 27898@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{234}@anchor{gnat_ugn/inline_assembler id3}@anchor{235} 27899@section A Simple Example of Inline Assembler 27900 27901 27902The following example will generate a single assembly language statement, 27903@code{nop}, which does nothing. Despite its lack of run-time effect, 27904the example will be useful in illustrating the basics of 27905the Inline Assembler facility. 27906 27907@quotation 27908 27909@example 27910with System.Machine_Code; use System.Machine_Code; 27911procedure Nothing is 27912begin 27913 Asm ("nop"); 27914end Nothing; 27915@end example 27916@end quotation 27917 27918@code{Asm} is a procedure declared in package @code{System.Machine_Code}; 27919here it takes one parameter, a @emph{template string} that must be a static 27920expression and that will form the generated instruction. 27921@code{Asm} may be regarded as a compile-time procedure that parses 27922the template string and additional parameters (none here), 27923from which it generates a sequence of assembly language instructions. 27924 27925The examples in this chapter will illustrate several of the forms 27926for invoking @code{Asm}; a complete specification of the syntax 27927is found in the @code{Machine_Code_Insertions} section of the 27928@cite{GNAT Reference Manual}. 27929 27930Under the standard GNAT conventions, the @code{Nothing} procedure 27931should be in a file named @code{nothing.adb}. 27932You can build the executable in the usual way: 27933 27934@quotation 27935 27936@example 27937$ gnatmake nothing 27938@end example 27939@end quotation 27940 27941However, the interesting aspect of this example is not its run-time behavior 27942but rather the generated assembly code. 27943To see this output, invoke the compiler as follows: 27944 27945@quotation 27946 27947@example 27948$ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb 27949@end example 27950@end quotation 27951 27952where the options are: 27953 27954 27955@itemize * 27956 27957@item 27958 27959@table @asis 27960 27961@item @code{-c} 27962 27963compile only (no bind or link) 27964@end table 27965 27966@item 27967 27968@table @asis 27969 27970@item @code{-S} 27971 27972generate assembler listing 27973@end table 27974 27975@item 27976 27977@table @asis 27978 27979@item @code{-fomit-frame-pointer} 27980 27981do not set up separate stack frames 27982@end table 27983 27984@item 27985 27986@table @asis 27987 27988@item @code{-gnatp} 27989 27990do not add runtime checks 27991@end table 27992@end itemize 27993 27994This gives a human-readable assembler version of the code. The resulting 27995file will have the same name as the Ada source file, but with a @code{.s} 27996extension. In our example, the file @code{nothing.s} has the following 27997contents: 27998 27999@quotation 28000 28001@example 28002.file "nothing.adb" 28003gcc2_compiled.: 28004___gnu_compiled_ada: 28005.text 28006 .align 4 28007.globl __ada_nothing 28008__ada_nothing: 28009#APP 28010 nop 28011#NO_APP 28012 jmp L1 28013 .align 2,0x90 28014L1: 28015 ret 28016@end example 28017@end quotation 28018 28019The assembly code you included is clearly indicated by 28020the compiler, between the @code{#APP} and @code{#NO_APP} 28021delimiters. The character before the 'APP' and 'NOAPP' 28022can differ on different targets. For example, GNU/Linux uses '#APP' while 28023on NT you will see '/APP'. 28024 28025If you make a mistake in your assembler code (such as using the 28026wrong size modifier, or using a wrong operand for the instruction) GNAT 28027will report this error in a temporary file, which will be deleted when 28028the compilation is finished. Generating an assembler file will help 28029in such cases, since you can assemble this file separately using the 28030@code{as} assembler that comes with gcc. 28031 28032Assembling the file using the command 28033 28034@quotation 28035 28036@example 28037$ as nothing.s 28038@end example 28039@end quotation 28040 28041will give you error messages whose lines correspond to the assembler 28042input file, so you can easily find and correct any mistakes you made. 28043If there are no errors, @code{as} will generate an object file 28044@code{nothing.out}. 28045 28046@node Output Variables in Inline Assembler,Input Variables in Inline Assembler,A Simple Example of Inline Assembler,Inline Assembler 28047@anchor{gnat_ugn/inline_assembler id4}@anchor{236}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{237} 28048@section Output Variables in Inline Assembler 28049 28050 28051The examples in this section, showing how to access the processor flags, 28052illustrate how to specify the destination operands for assembly language 28053statements. 28054 28055@quotation 28056 28057@example 28058with Interfaces; use Interfaces; 28059with Ada.Text_IO; use Ada.Text_IO; 28060with System.Machine_Code; use System.Machine_Code; 28061procedure Get_Flags is 28062 Flags : Unsigned_32; 28063 use ASCII; 28064begin 28065 Asm ("pushfl" & LF & HT & -- push flags on stack 28066 "popl %%eax" & LF & HT & -- load eax with flags 28067 "movl %%eax, %0", -- store flags in variable 28068 Outputs => Unsigned_32'Asm_Output ("=g", Flags)); 28069 Put_Line ("Flags register:" & Flags'Img); 28070end Get_Flags; 28071@end example 28072@end quotation 28073 28074In order to have a nicely aligned assembly listing, we have separated 28075multiple assembler statements in the Asm template string with linefeed 28076(ASCII.LF) and horizontal tab (ASCII.HT) characters. 28077The resulting section of the assembly output file is: 28078 28079@quotation 28080 28081@example 28082#APP 28083 pushfl 28084 popl %eax 28085 movl %eax, -40(%ebp) 28086#NO_APP 28087@end example 28088@end quotation 28089 28090It would have been legal to write the Asm invocation as: 28091 28092@quotation 28093 28094@example 28095Asm ("pushfl popl %%eax movl %%eax, %0") 28096@end example 28097@end quotation 28098 28099but in the generated assembler file, this would come out as: 28100 28101@quotation 28102 28103@example 28104#APP 28105 pushfl popl %eax movl %eax, -40(%ebp) 28106#NO_APP 28107@end example 28108@end quotation 28109 28110which is not so convenient for the human reader. 28111 28112We use Ada comments 28113at the end of each line to explain what the assembler instructions 28114actually do. This is a useful convention. 28115 28116When writing Inline Assembler instructions, you need to precede each register 28117and variable name with a percent sign. Since the assembler already requires 28118a percent sign at the beginning of a register name, you need two consecutive 28119percent signs for such names in the Asm template string, thus @code{%%eax}. 28120In the generated assembly code, one of the percent signs will be stripped off. 28121 28122Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output 28123variables: operands you later define using @code{Input} or @code{Output} 28124parameters to @code{Asm}. 28125An output variable is illustrated in 28126the third statement in the Asm template string: 28127 28128@quotation 28129 28130@example 28131movl %%eax, %0 28132@end example 28133@end quotation 28134 28135The intent is to store the contents of the eax register in a variable that can 28136be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not 28137necessarily work, since the compiler might optimize by using a register 28138to hold Flags, and the expansion of the @code{movl} instruction would not be 28139aware of this optimization. The solution is not to store the result directly 28140but rather to advise the compiler to choose the correct operand form; 28141that is the purpose of the @code{%0} output variable. 28142 28143Information about the output variable is supplied in the @code{Outputs} 28144parameter to @code{Asm}: 28145 28146@quotation 28147 28148@example 28149Outputs => Unsigned_32'Asm_Output ("=g", Flags)); 28150@end example 28151@end quotation 28152 28153The output is defined by the @code{Asm_Output} attribute of the target type; 28154the general format is 28155 28156@quotation 28157 28158@example 28159Type'Asm_Output (constraint_string, variable_name) 28160@end example 28161@end quotation 28162 28163The constraint string directs the compiler how 28164to store/access the associated variable. In the example 28165 28166@quotation 28167 28168@example 28169Unsigned_32'Asm_Output ("=m", Flags); 28170@end example 28171@end quotation 28172 28173the @code{"m"} (memory) constraint tells the compiler that the variable 28174@code{Flags} should be stored in a memory variable, thus preventing 28175the optimizer from keeping it in a register. In contrast, 28176 28177@quotation 28178 28179@example 28180Unsigned_32'Asm_Output ("=r", Flags); 28181@end example 28182@end quotation 28183 28184uses the @code{"r"} (register) constraint, telling the compiler to 28185store the variable in a register. 28186 28187If the constraint is preceded by the equal character '=', it tells 28188the compiler that the variable will be used to store data into it. 28189 28190In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint, 28191allowing the optimizer to choose whatever it deems best. 28192 28193There are a fairly large number of constraints, but the ones that are 28194most useful (for the Intel x86 processor) are the following: 28195 28196@quotation 28197 28198 28199@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 28200@item 28201 28202@emph{=} 28203 28204@tab 28205 28206output constraint 28207 28208@item 28209 28210@emph{g} 28211 28212@tab 28213 28214global (i.e., can be stored anywhere) 28215 28216@item 28217 28218@emph{m} 28219 28220@tab 28221 28222in memory 28223 28224@item 28225 28226@emph{I} 28227 28228@tab 28229 28230a constant 28231 28232@item 28233 28234@emph{a} 28235 28236@tab 28237 28238use eax 28239 28240@item 28241 28242@emph{b} 28243 28244@tab 28245 28246use ebx 28247 28248@item 28249 28250@emph{c} 28251 28252@tab 28253 28254use ecx 28255 28256@item 28257 28258@emph{d} 28259 28260@tab 28261 28262use edx 28263 28264@item 28265 28266@emph{S} 28267 28268@tab 28269 28270use esi 28271 28272@item 28273 28274@emph{D} 28275 28276@tab 28277 28278use edi 28279 28280@item 28281 28282@emph{r} 28283 28284@tab 28285 28286use one of eax, ebx, ecx or edx 28287 28288@item 28289 28290@emph{q} 28291 28292@tab 28293 28294use one of eax, ebx, ecx, edx, esi or edi 28295 28296@end multitable 28297 28298@end quotation 28299 28300The full set of constraints is described in the gcc and @code{as} 28301documentation; note that it is possible to combine certain constraints 28302in one constraint string. 28303 28304You specify the association of an output variable with an assembler operand 28305through the @code{%@emph{n}} notation, where @emph{n} is a non-negative 28306integer. Thus in 28307 28308@quotation 28309 28310@example 28311Asm ("pushfl" & LF & HT & -- push flags on stack 28312 "popl %%eax" & LF & HT & -- load eax with flags 28313 "movl %%eax, %0", -- store flags in variable 28314 Outputs => Unsigned_32'Asm_Output ("=g", Flags)); 28315@end example 28316@end quotation 28317 28318@code{%0} will be replaced in the expanded code by the appropriate operand, 28319whatever 28320the compiler decided for the @code{Flags} variable. 28321 28322In general, you may have any number of output variables: 28323 28324 28325@itemize * 28326 28327@item 28328Count the operands starting at 0; thus @code{%0}, @code{%1}, etc. 28329 28330@item 28331Specify the @code{Outputs} parameter as a parenthesized comma-separated list 28332of @code{Asm_Output} attributes 28333@end itemize 28334 28335For example: 28336 28337@quotation 28338 28339@example 28340Asm ("movl %%eax, %0" & LF & HT & 28341 "movl %%ebx, %1" & LF & HT & 28342 "movl %%ecx, %2", 28343 Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A 28344 Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B 28345 Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C 28346@end example 28347@end quotation 28348 28349where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables 28350in the Ada program. 28351 28352As a variation on the @code{Get_Flags} example, we can use the constraints 28353string to direct the compiler to store the eax register into the @code{Flags} 28354variable, instead of including the store instruction explicitly in the 28355@code{Asm} template string: 28356 28357@quotation 28358 28359@example 28360with Interfaces; use Interfaces; 28361with Ada.Text_IO; use Ada.Text_IO; 28362with System.Machine_Code; use System.Machine_Code; 28363procedure Get_Flags_2 is 28364 Flags : Unsigned_32; 28365 use ASCII; 28366begin 28367 Asm ("pushfl" & LF & HT & -- push flags on stack 28368 "popl %%eax", -- save flags in eax 28369 Outputs => Unsigned_32'Asm_Output ("=a", Flags)); 28370 Put_Line ("Flags register:" & Flags'Img); 28371end Get_Flags_2; 28372@end example 28373@end quotation 28374 28375The @code{"a"} constraint tells the compiler that the @code{Flags} 28376variable will come from the eax register. Here is the resulting code: 28377 28378@quotation 28379 28380@example 28381#APP 28382 pushfl 28383 popl %eax 28384#NO_APP 28385 movl %eax,-40(%ebp) 28386@end example 28387@end quotation 28388 28389The compiler generated the store of eax into Flags after 28390expanding the assembler code. 28391 28392Actually, there was no need to pop the flags into the eax register; 28393more simply, we could just pop the flags directly into the program variable: 28394 28395@quotation 28396 28397@example 28398with Interfaces; use Interfaces; 28399with Ada.Text_IO; use Ada.Text_IO; 28400with System.Machine_Code; use System.Machine_Code; 28401procedure Get_Flags_3 is 28402 Flags : Unsigned_32; 28403 use ASCII; 28404begin 28405 Asm ("pushfl" & LF & HT & -- push flags on stack 28406 "pop %0", -- save flags in Flags 28407 Outputs => Unsigned_32'Asm_Output ("=g", Flags)); 28408 Put_Line ("Flags register:" & Flags'Img); 28409end Get_Flags_3; 28410@end example 28411@end quotation 28412 28413@node Input Variables in Inline Assembler,Inlining Inline Assembler Code,Output Variables in Inline Assembler,Inline Assembler 28414@anchor{gnat_ugn/inline_assembler id5}@anchor{238}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{239} 28415@section Input Variables in Inline Assembler 28416 28417 28418The example in this section illustrates how to specify the source operands 28419for assembly language statements. 28420The program simply increments its input value by 1: 28421 28422@quotation 28423 28424@example 28425with Interfaces; use Interfaces; 28426with Ada.Text_IO; use Ada.Text_IO; 28427with System.Machine_Code; use System.Machine_Code; 28428procedure Increment is 28429 28430 function Incr (Value : Unsigned_32) return Unsigned_32 is 28431 Result : Unsigned_32; 28432 begin 28433 Asm ("incl %0", 28434 Outputs => Unsigned_32'Asm_Output ("=a", Result), 28435 Inputs => Unsigned_32'Asm_Input ("a", Value)); 28436 return Result; 28437 end Incr; 28438 28439 Value : Unsigned_32; 28440 28441begin 28442 Value := 5; 28443 Put_Line ("Value before is" & Value'Img); 28444 Value := Incr (Value); 28445 Put_Line ("Value after is" & Value'Img); 28446end Increment; 28447@end example 28448@end quotation 28449 28450The @code{Outputs} parameter to @code{Asm} specifies 28451that the result will be in the eax register and that it is to be stored 28452in the @code{Result} variable. 28453 28454The @code{Inputs} parameter looks much like the @code{Outputs} parameter, 28455but with an @code{Asm_Input} attribute. 28456The @code{"="} constraint, indicating an output value, is not present. 28457 28458You can have multiple input variables, in the same way that you can have more 28459than one output variable. 28460 28461The parameter count (%0, %1) etc, still starts at the first output statement, 28462and continues with the input statements. 28463 28464Just as the @code{Outputs} parameter causes the register to be stored into the 28465target variable after execution of the assembler statements, so does the 28466@code{Inputs} parameter cause its variable to be loaded into the register 28467before execution of the assembler statements. 28468 28469Thus the effect of the @code{Asm} invocation is: 28470 28471 28472@itemize * 28473 28474@item 28475load the 32-bit value of @code{Value} into eax 28476 28477@item 28478execute the @code{incl %eax} instruction 28479 28480@item 28481store the contents of eax into the @code{Result} variable 28482@end itemize 28483 28484The resulting assembler file (with @code{-O2} optimization) contains: 28485 28486@quotation 28487 28488@example 28489_increment__incr.1: 28490 subl $4,%esp 28491 movl 8(%esp),%eax 28492#APP 28493 incl %eax 28494#NO_APP 28495 movl %eax,%edx 28496 movl %ecx,(%esp) 28497 addl $4,%esp 28498 ret 28499@end example 28500@end quotation 28501 28502@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler 28503@anchor{gnat_ugn/inline_assembler id6}@anchor{23a}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23b} 28504@section Inlining Inline Assembler Code 28505 28506 28507For a short subprogram such as the @code{Incr} function in the previous 28508section, the overhead of the call and return (creating / deleting the stack 28509frame) can be significant, compared to the amount of code in the subprogram 28510body. A solution is to apply Ada's @code{Inline} pragma to the subprogram, 28511which directs the compiler to expand invocations of the subprogram at the 28512point(s) of call, instead of setting up a stack frame for out-of-line calls. 28513Here is the resulting program: 28514 28515@quotation 28516 28517@example 28518with Interfaces; use Interfaces; 28519with Ada.Text_IO; use Ada.Text_IO; 28520with System.Machine_Code; use System.Machine_Code; 28521procedure Increment_2 is 28522 28523 function Incr (Value : Unsigned_32) return Unsigned_32 is 28524 Result : Unsigned_32; 28525 begin 28526 Asm ("incl %0", 28527 Outputs => Unsigned_32'Asm_Output ("=a", Result), 28528 Inputs => Unsigned_32'Asm_Input ("a", Value)); 28529 return Result; 28530 end Incr; 28531 pragma Inline (Increment); 28532 28533 Value : Unsigned_32; 28534 28535begin 28536 Value := 5; 28537 Put_Line ("Value before is" & Value'Img); 28538 Value := Increment (Value); 28539 Put_Line ("Value after is" & Value'Img); 28540end Increment_2; 28541@end example 28542@end quotation 28543 28544Compile the program with both optimization (@code{-O2}) and inlining 28545(@code{-gnatn}) enabled. 28546 28547The @code{Incr} function is still compiled as usual, but at the 28548point in @code{Increment} where our function used to be called: 28549 28550@quotation 28551 28552@example 28553pushl %edi 28554call _increment__incr.1 28555@end example 28556@end quotation 28557 28558the code for the function body directly appears: 28559 28560@quotation 28561 28562@example 28563movl %esi,%eax 28564#APP 28565 incl %eax 28566#NO_APP 28567 movl %eax,%edx 28568@end example 28569@end quotation 28570 28571thus saving the overhead of stack frame setup and an out-of-line call. 28572 28573@node Other Asm Functionality,,Inlining Inline Assembler Code,Inline Assembler 28574@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23c}@anchor{gnat_ugn/inline_assembler id7}@anchor{23d} 28575@section Other @code{Asm} Functionality 28576 28577 28578This section describes two important parameters to the @code{Asm} 28579procedure: @code{Clobber}, which identifies register usage; 28580and @code{Volatile}, which inhibits unwanted optimizations. 28581 28582@menu 28583* The Clobber Parameter:: 28584* The Volatile Parameter:: 28585 28586@end menu 28587 28588@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality 28589@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{23e}@anchor{gnat_ugn/inline_assembler id8}@anchor{23f} 28590@subsection The @code{Clobber} Parameter 28591 28592 28593One of the dangers of intermixing assembly language and a compiled language 28594such as Ada is that the compiler needs to be aware of which registers are 28595being used by the assembly code. In some cases, such as the earlier examples, 28596the constraint string is sufficient to indicate register usage (e.g., 28597@code{"a"} for 28598the eax register). But more generally, the compiler needs an explicit 28599identification of the registers that are used by the Inline Assembly 28600statements. 28601 28602Using a register that the compiler doesn't know about 28603could be a side effect of an instruction (like @code{mull} 28604storing its result in both eax and edx). 28605It can also arise from explicit register usage in your 28606assembly code; for example: 28607 28608@quotation 28609 28610@example 28611Asm ("movl %0, %%ebx" & LF & HT & 28612 "movl %%ebx, %1", 28613 Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), 28614 Inputs => Unsigned_32'Asm_Input ("g", Var_In)); 28615@end example 28616@end quotation 28617 28618where the compiler (since it does not analyze the @code{Asm} template string) 28619does not know you are using the ebx register. 28620 28621In such cases you need to supply the @code{Clobber} parameter to @code{Asm}, 28622to identify the registers that will be used by your assembly code: 28623 28624@quotation 28625 28626@example 28627Asm ("movl %0, %%ebx" & LF & HT & 28628 "movl %%ebx, %1", 28629 Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), 28630 Inputs => Unsigned_32'Asm_Input ("g", Var_In), 28631 Clobber => "ebx"); 28632@end example 28633@end quotation 28634 28635The Clobber parameter is a static string expression specifying the 28636register(s) you are using. Note that register names are @emph{not} prefixed 28637by a percent sign. Also, if more than one register is used then their names 28638are separated by commas; e.g., @code{"eax, ebx"} 28639 28640The @code{Clobber} parameter has several additional uses: 28641 28642 28643@itemize * 28644 28645@item 28646Use 'register' name @code{cc} to indicate that flags might have changed 28647 28648@item 28649Use 'register' name @code{memory} if you changed a memory location 28650@end itemize 28651 28652@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality 28653@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{240}@anchor{gnat_ugn/inline_assembler id9}@anchor{241} 28654@subsection The @code{Volatile} Parameter 28655 28656 28657@geindex Volatile parameter 28658 28659Compiler optimizations in the presence of Inline Assembler may sometimes have 28660unwanted effects. For example, when an @code{Asm} invocation with an input 28661variable is inside a loop, the compiler might move the loading of the input 28662variable outside the loop, regarding it as a one-time initialization. 28663 28664If this effect is not desired, you can disable such optimizations by setting 28665the @code{Volatile} parameter to @code{True}; for example: 28666 28667@quotation 28668 28669@example 28670Asm ("movl %0, %%ebx" & LF & HT & 28671 "movl %%ebx, %1", 28672 Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), 28673 Inputs => Unsigned_32'Asm_Input ("g", Var_In), 28674 Clobber => "ebx", 28675 Volatile => True); 28676@end example 28677@end quotation 28678 28679By default, @code{Volatile} is set to @code{False} unless there is no 28680@code{Outputs} parameter. 28681 28682Although setting @code{Volatile} to @code{True} prevents unwanted 28683optimizations, it will also disable other optimizations that might be 28684important for efficiency. In general, you should set @code{Volatile} 28685to @code{True} only if the compiler's optimizations have created 28686problems. 28687 28688@node GNU Free Documentation License,Index,Inline Assembler,Top 28689@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{242}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{243} 28690@chapter GNU Free Documentation License 28691 28692 28693Version 1.3, 3 November 2008 28694 28695Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 28696@indicateurl{http://fsf.org/} 28697 28698Everyone is permitted to copy and distribute verbatim copies of this 28699license document, but changing it is not allowed. 28700 28701@strong{Preamble} 28702 28703The purpose of this License is to make a manual, textbook, or other 28704functional and useful document "free" in the sense of freedom: to 28705assure everyone the effective freedom to copy and redistribute it, 28706with or without modifying it, either commercially or noncommercially. 28707Secondarily, this License preserves for the author and publisher a way 28708to get credit for their work, while not being considered responsible 28709for modifications made by others. 28710 28711This License is a kind of "copyleft", which means that derivative 28712works of the document must themselves be free in the same sense. It 28713complements the GNU General Public License, which is a copyleft 28714license designed for free software. 28715 28716We have designed this License in order to use it for manuals for free 28717software, because free software needs free documentation: a free 28718program should come with manuals providing the same freedoms that the 28719software does. But this License is not limited to software manuals; 28720it can be used for any textual work, regardless of subject matter or 28721whether it is published as a printed book. We recommend this License 28722principally for works whose purpose is instruction or reference. 28723 28724@strong{1. APPLICABILITY AND DEFINITIONS} 28725 28726This License applies to any manual or other work, in any medium, that 28727contains a notice placed by the copyright holder saying it can be 28728distributed under the terms of this License. Such a notice grants a 28729world-wide, royalty-free license, unlimited in duration, to use that 28730work under the conditions stated herein. The @strong{Document}, below, 28731refers to any such manual or work. Any member of the public is a 28732licensee, and is addressed as "@strong{you}". You accept the license if you 28733copy, modify or distribute the work in a way requiring permission 28734under copyright law. 28735 28736A "@strong{Modified Version}" of the Document means any work containing the 28737Document or a portion of it, either copied verbatim, or with 28738modifications and/or translated into another language. 28739 28740A "@strong{Secondary Section}" is a named appendix or a front-matter section of 28741the Document that deals exclusively with the relationship of the 28742publishers or authors of the Document to the Document's overall subject 28743(or to related matters) and contains nothing that could fall directly 28744within that overall subject. (Thus, if the Document is in part a 28745textbook of mathematics, a Secondary Section may not explain any 28746mathematics.) The relationship could be a matter of historical 28747connection with the subject or with related matters, or of legal, 28748commercial, philosophical, ethical or political position regarding 28749them. 28750 28751The "@strong{Invariant Sections}" are certain Secondary Sections whose titles 28752are designated, as being those of Invariant Sections, in the notice 28753that says that the Document is released under this License. If a 28754section does not fit the above definition of Secondary then it is not 28755allowed to be designated as Invariant. The Document may contain zero 28756Invariant Sections. If the Document does not identify any Invariant 28757Sections then there are none. 28758 28759The "@strong{Cover Texts}" are certain short passages of text that are listed, 28760as Front-Cover Texts or Back-Cover Texts, in the notice that says that 28761the Document is released under this License. A Front-Cover Text may 28762be at most 5 words, and a Back-Cover Text may be at most 25 words. 28763 28764A "@strong{Transparent}" copy of the Document means a machine-readable copy, 28765represented in a format whose specification is available to the 28766general public, that is suitable for revising the document 28767straightforwardly with generic text editors or (for images composed of 28768pixels) generic paint programs or (for drawings) some widely available 28769drawing editor, and that is suitable for input to text formatters or 28770for automatic translation to a variety of formats suitable for input 28771to text formatters. A copy made in an otherwise Transparent file 28772format whose markup, or absence of markup, has been arranged to thwart 28773or discourage subsequent modification by readers is not Transparent. 28774An image format is not Transparent if used for any substantial amount 28775of text. A copy that is not "Transparent" is called @strong{Opaque}. 28776 28777Examples of suitable formats for Transparent copies include plain 28778ASCII without markup, Texinfo input format, LaTeX input format, SGML 28779or XML using a publicly available DTD, and standard-conforming simple 28780HTML, PostScript or PDF designed for human modification. Examples of 28781transparent image formats include PNG, XCF and JPG. Opaque formats 28782include proprietary formats that can be read and edited only by 28783proprietary word processors, SGML or XML for which the DTD and/or 28784processing tools are not generally available, and the 28785machine-generated HTML, PostScript or PDF produced by some word 28786processors for output purposes only. 28787 28788The "@strong{Title Page}" means, for a printed book, the title page itself, 28789plus such following pages as are needed to hold, legibly, the material 28790this License requires to appear in the title page. For works in 28791formats which do not have any title page as such, "Title Page" means 28792the text near the most prominent appearance of the work's title, 28793preceding the beginning of the body of the text. 28794 28795The "@strong{publisher}" means any person or entity that distributes 28796copies of the Document to the public. 28797 28798A section "@strong{Entitled XYZ}" means a named subunit of the Document whose 28799title either is precisely XYZ or contains XYZ in parentheses following 28800text that translates XYZ in another language. (Here XYZ stands for a 28801specific section name mentioned below, such as "@strong{Acknowledgements}", 28802"@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) 28803To "@strong{Preserve the Title}" 28804of such a section when you modify the Document means that it remains a 28805section "Entitled XYZ" according to this definition. 28806 28807The Document may include Warranty Disclaimers next to the notice which 28808states that this License applies to the Document. These Warranty 28809Disclaimers are considered to be included by reference in this 28810License, but only as regards disclaiming warranties: any other 28811implication that these Warranty Disclaimers may have is void and has 28812no effect on the meaning of this License. 28813 28814@strong{2. VERBATIM COPYING} 28815 28816You may copy and distribute the Document in any medium, either 28817commercially or noncommercially, provided that this License, the 28818copyright notices, and the license notice saying this License applies 28819to the Document are reproduced in all copies, and that you add no other 28820conditions whatsoever to those of this License. You may not use 28821technical measures to obstruct or control the reading or further 28822copying of the copies you make or distribute. However, you may accept 28823compensation in exchange for copies. If you distribute a large enough 28824number of copies you must also follow the conditions in section 3. 28825 28826You may also lend copies, under the same conditions stated above, and 28827you may publicly display copies. 28828 28829@strong{3. COPYING IN QUANTITY} 28830 28831If you publish printed copies (or copies in media that commonly have 28832printed covers) of the Document, numbering more than 100, and the 28833Document's license notice requires Cover Texts, you must enclose the 28834copies in covers that carry, clearly and legibly, all these Cover 28835Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 28836the back cover. Both covers must also clearly and legibly identify 28837you as the publisher of these copies. The front cover must present 28838the full title with all words of the title equally prominent and 28839visible. You may add other material on the covers in addition. 28840Copying with changes limited to the covers, as long as they preserve 28841the title of the Document and satisfy these conditions, can be treated 28842as verbatim copying in other respects. 28843 28844If the required texts for either cover are too voluminous to fit 28845legibly, you should put the first ones listed (as many as fit 28846reasonably) on the actual cover, and continue the rest onto adjacent 28847pages. 28848 28849If you publish or distribute Opaque copies of the Document numbering 28850more than 100, you must either include a machine-readable Transparent 28851copy along with each Opaque copy, or state in or with each Opaque copy 28852a computer-network location from which the general network-using 28853public has access to download using public-standard network protocols 28854a complete Transparent copy of the Document, free of added material. 28855If you use the latter option, you must take reasonably prudent steps, 28856when you begin distribution of Opaque copies in quantity, to ensure 28857that this Transparent copy will remain thus accessible at the stated 28858location until at least one year after the last time you distribute an 28859Opaque copy (directly or through your agents or retailers) of that 28860edition to the public. 28861 28862It is requested, but not required, that you contact the authors of the 28863Document well before redistributing any large number of copies, to give 28864them a chance to provide you with an updated version of the Document. 28865 28866@strong{4. MODIFICATIONS} 28867 28868You may copy and distribute a Modified Version of the Document under 28869the conditions of sections 2 and 3 above, provided that you release 28870the Modified Version under precisely this License, with the Modified 28871Version filling the role of the Document, thus licensing distribution 28872and modification of the Modified Version to whoever possesses a copy 28873of it. In addition, you must do these things in the Modified Version: 28874 28875 28876@enumerate A 28877 28878@item 28879Use in the Title Page (and on the covers, if any) a title distinct 28880from that of the Document, and from those of previous versions 28881(which should, if there were any, be listed in the History section 28882of the Document). You may use the same title as a previous version 28883if the original publisher of that version gives permission. 28884 28885@item 28886List on the Title Page, as authors, one or more persons or entities 28887responsible for authorship of the modifications in the Modified 28888Version, together with at least five of the principal authors of the 28889Document (all of its principal authors, if it has fewer than five), 28890unless they release you from this requirement. 28891 28892@item 28893State on the Title page the name of the publisher of the 28894Modified Version, as the publisher. 28895 28896@item 28897Preserve all the copyright notices of the Document. 28898 28899@item 28900Add an appropriate copyright notice for your modifications 28901adjacent to the other copyright notices. 28902 28903@item 28904Include, immediately after the copyright notices, a license notice 28905giving the public permission to use the Modified Version under the 28906terms of this License, in the form shown in the Addendum below. 28907 28908@item 28909Preserve in that license notice the full lists of Invariant Sections 28910and required Cover Texts given in the Document's license notice. 28911 28912@item 28913Include an unaltered copy of this License. 28914 28915@item 28916Preserve the section Entitled "History", Preserve its Title, and add 28917to it an item stating at least the title, year, new authors, and 28918publisher of the Modified Version as given on the Title Page. If 28919there is no section Entitled "History" in the Document, create one 28920stating the title, year, authors, and publisher of the Document as 28921given on its Title Page, then add an item describing the Modified 28922Version as stated in the previous sentence. 28923 28924@item 28925Preserve the network location, if any, given in the Document for 28926public access to a Transparent copy of the Document, and likewise 28927the network locations given in the Document for previous versions 28928it was based on. These may be placed in the "History" section. 28929You may omit a network location for a work that was published at 28930least four years before the Document itself, or if the original 28931publisher of the version it refers to gives permission. 28932 28933@item 28934For any section Entitled "Acknowledgements" or "Dedications", 28935Preserve the Title of the section, and preserve in the section all 28936the substance and tone of each of the contributor acknowledgements 28937and/or dedications given therein. 28938 28939@item 28940Preserve all the Invariant Sections of the Document, 28941unaltered in their text and in their titles. Section numbers 28942or the equivalent are not considered part of the section titles. 28943 28944@item 28945Delete any section Entitled "Endorsements". Such a section 28946may not be included in the Modified Version. 28947 28948@item 28949Do not retitle any existing section to be Entitled "Endorsements" 28950or to conflict in title with any Invariant Section. 28951 28952@item 28953Preserve any Warranty Disclaimers. 28954@end enumerate 28955 28956If the Modified Version includes new front-matter sections or 28957appendices that qualify as Secondary Sections and contain no material 28958copied from the Document, you may at your option designate some or all 28959of these sections as invariant. To do this, add their titles to the 28960list of Invariant Sections in the Modified Version's license notice. 28961These titles must be distinct from any other section titles. 28962 28963You may add a section Entitled "Endorsements", provided it contains 28964nothing but endorsements of your Modified Version by various 28965parties---for example, statements of peer review or that the text has 28966been approved by an organization as the authoritative definition of a 28967standard. 28968 28969You may add a passage of up to five words as a Front-Cover Text, and a 28970passage of up to 25 words as a Back-Cover Text, to the end of the list 28971of Cover Texts in the Modified Version. Only one passage of 28972Front-Cover Text and one of Back-Cover Text may be added by (or 28973through arrangements made by) any one entity. If the Document already 28974includes a cover text for the same cover, previously added by you or 28975by arrangement made by the same entity you are acting on behalf of, 28976you may not add another; but you may replace the old one, on explicit 28977permission from the previous publisher that added the old one. 28978 28979The author(s) and publisher(s) of the Document do not by this License 28980give permission to use their names for publicity for or to assert or 28981imply endorsement of any Modified Version. 28982 28983@strong{5. COMBINING DOCUMENTS} 28984 28985You may combine the Document with other documents released under this 28986License, under the terms defined in section 4 above for modified 28987versions, provided that you include in the combination all of the 28988Invariant Sections of all of the original documents, unmodified, and 28989list them all as Invariant Sections of your combined work in its 28990license notice, and that you preserve all their Warranty Disclaimers. 28991 28992The combined work need only contain one copy of this License, and 28993multiple identical Invariant Sections may be replaced with a single 28994copy. If there are multiple Invariant Sections with the same name but 28995different contents, make the title of each such section unique by 28996adding at the end of it, in parentheses, the name of the original 28997author or publisher of that section if known, or else a unique number. 28998Make the same adjustment to the section titles in the list of 28999Invariant Sections in the license notice of the combined work. 29000 29001In the combination, you must combine any sections Entitled "History" 29002in the various original documents, forming one section Entitled 29003"History"; likewise combine any sections Entitled "Acknowledgements", 29004and any sections Entitled "Dedications". You must delete all sections 29005Entitled "Endorsements". 29006 29007@strong{6. COLLECTIONS OF DOCUMENTS} 29008 29009You may make a collection consisting of the Document and other documents 29010released under this License, and replace the individual copies of this 29011License in the various documents with a single copy that is included in 29012the collection, provided that you follow the rules of this License for 29013verbatim copying of each of the documents in all other respects. 29014 29015You may extract a single document from such a collection, and distribute 29016it individually under this License, provided you insert a copy of this 29017License into the extracted document, and follow this License in all 29018other respects regarding verbatim copying of that document. 29019 29020@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 29021 29022A compilation of the Document or its derivatives with other separate 29023and independent documents or works, in or on a volume of a storage or 29024distribution medium, is called an "aggregate" if the copyright 29025resulting from the compilation is not used to limit the legal rights 29026of the compilation's users beyond what the individual works permit. 29027When the Document is included in an aggregate, this License does not 29028apply to the other works in the aggregate which are not themselves 29029derivative works of the Document. 29030 29031If the Cover Text requirement of section 3 is applicable to these 29032copies of the Document, then if the Document is less than one half of 29033the entire aggregate, the Document's Cover Texts may be placed on 29034covers that bracket the Document within the aggregate, or the 29035electronic equivalent of covers if the Document is in electronic form. 29036Otherwise they must appear on printed covers that bracket the whole 29037aggregate. 29038 29039@strong{8. TRANSLATION} 29040 29041Translation is considered a kind of modification, so you may 29042distribute translations of the Document under the terms of section 4. 29043Replacing Invariant Sections with translations requires special 29044permission from their copyright holders, but you may include 29045translations of some or all Invariant Sections in addition to the 29046original versions of these Invariant Sections. You may include a 29047translation of this License, and all the license notices in the 29048Document, and any Warranty Disclaimers, provided that you also include 29049the original English version of this License and the original versions 29050of those notices and disclaimers. In case of a disagreement between 29051the translation and the original version of this License or a notice 29052or disclaimer, the original version will prevail. 29053 29054If a section in the Document is Entitled "Acknowledgements", 29055"Dedications", or "History", the requirement (section 4) to Preserve 29056its Title (section 1) will typically require changing the actual 29057title. 29058 29059@strong{9. TERMINATION} 29060 29061You may not copy, modify, sublicense, or distribute the Document 29062except as expressly provided under this License. Any attempt 29063otherwise to copy, modify, sublicense, or distribute it is void, and 29064will automatically terminate your rights under this License. 29065 29066However, if you cease all violation of this License, then your license 29067from a particular copyright holder is reinstated (a) provisionally, 29068unless and until the copyright holder explicitly and finally 29069terminates your license, and (b) permanently, if the copyright holder 29070fails to notify you of the violation by some reasonable means prior to 2907160 days after the cessation. 29072 29073Moreover, your license from a particular copyright holder is 29074reinstated permanently if the copyright holder notifies you of the 29075violation by some reasonable means, this is the first time you have 29076received notice of violation of this License (for any work) from that 29077copyright holder, and you cure the violation prior to 30 days after 29078your receipt of the notice. 29079 29080Termination of your rights under this section does not terminate the 29081licenses of parties who have received copies or rights from you under 29082this License. If your rights have been terminated and not permanently 29083reinstated, receipt of a copy of some or all of the same material does 29084not give you any rights to use it. 29085 29086@strong{10. FUTURE REVISIONS OF THIS LICENSE} 29087 29088The Free Software Foundation may publish new, revised versions 29089of the GNU Free Documentation License from time to time. Such new 29090versions will be similar in spirit to the present version, but may 29091differ in detail to address new problems or concerns. See 29092@indicateurl{http://www.gnu.org/copyleft/}. 29093 29094Each version of the License is given a distinguishing version number. 29095If the Document specifies that a particular numbered version of this 29096License "or any later version" applies to it, you have the option of 29097following the terms and conditions either of that specified version or 29098of any later version that has been published (not as a draft) by the 29099Free Software Foundation. If the Document does not specify a version 29100number of this License, you may choose any version ever published (not 29101as a draft) by the Free Software Foundation. If the Document 29102specifies that a proxy can decide which future versions of this 29103License can be used, that proxy's public statement of acceptance of a 29104version permanently authorizes you to choose that version for the 29105Document. 29106 29107@strong{11. RELICENSING} 29108 29109"Massive Multiauthor Collaboration Site" (or "MMC Site") means any 29110World Wide Web server that publishes copyrightable works and also 29111provides prominent facilities for anybody to edit those works. A 29112public wiki that anybody can edit is an example of such a server. A 29113"Massive Multiauthor Collaboration" (or "MMC") contained in the 29114site means any set of copyrightable works thus published on the MMC 29115site. 29116 29117"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 29118license published by Creative Commons Corporation, a not-for-profit 29119corporation with a principal place of business in San Francisco, 29120California, as well as future copyleft versions of that license 29121published by that same organization. 29122 29123"Incorporate" means to publish or republish a Document, in whole or 29124in part, as part of another Document. 29125 29126An MMC is "eligible for relicensing" if it is licensed under this 29127License, and if all works that were first published under this License 29128somewhere other than this MMC, and subsequently incorporated in whole 29129or in part into the MMC, (1) had no cover texts or invariant sections, 29130and (2) were thus incorporated prior to November 1, 2008. 29131 29132The operator of an MMC Site may republish an MMC contained in the site 29133under CC-BY-SA on the same site at any time before August 1, 2009, 29134provided the MMC is eligible for relicensing. 29135 29136@strong{ADDENDUM: How to use this License for your documents} 29137 29138To use this License in a document you have written, include a copy of 29139the License in the document and put the following copyright and 29140license notices just after the title page: 29141 29142@quotation 29143 29144Copyright © YEAR YOUR NAME. 29145Permission is granted to copy, distribute and/or modify this document 29146under the terms of the GNU Free Documentation License, Version 1.3 29147or any later version published by the Free Software Foundation; 29148with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 29149A copy of the license is included in the section entitled "GNU 29150Free Documentation License". 29151@end quotation 29152 29153If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 29154replace the "with ... Texts." line with this: 29155 29156@quotation 29157 29158with the Invariant Sections being LIST THEIR TITLES, with the 29159Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 29160@end quotation 29161 29162If you have Invariant Sections without Cover Texts, or some other 29163combination of the three, merge those two alternatives to suit the 29164situation. 29165 29166If your document contains nontrivial examples of program code, we 29167recommend releasing these examples in parallel under your choice of 29168free software license, such as the GNU General Public License, 29169to permit their use in free software. 29170 29171@node Index,,GNU Free Documentation License,Top 29172@unnumbered Index 29173 29174 29175@printindex ge 29176 29177@anchor{gnat_ugn/gnat_utility_programs switches-related-to-project-files}@w{ } 29178@anchor{cf}@w{ } 29179 29180@c %**end of body 29181@bye 29182