GNAT User’s Guide for Native Platforms Release 23.0w AdaCore Sep 29, 2021 GNAT User’s Guide for Native Platforms 23.0w This page is intentionally left blank. 2 of 332 GNAT User’s Guide for Native Platforms GNAT User’s Guide for Native Platforms 23.0w GNAT, The GNU Ada Development Environment GNAT Pro Edition Version 23.0w Date: Sep 29, 2021 AdaCore Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “GNAT Reference Manual”, and with no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. GNAT User’s Guide for Native Platforms 3 of 332 GNAT User’s Guide for Native Platforms 23.0w This page is intentionally left blank. 4 of 332 GNAT User’s Guide for Native Platforms GNAT User’s Guide for Native Platforms 23.0w CONTENTS 1 About This Guide 13 1.1 What This Guide Contains........................................ 13 1.2 What You Should Know before Reading This Guide........................... 14 1.3 Related Information............................................ 14 1.4 Conventions................................................ 14 2 Getting Started with GNAT 15 2.1 System Requirements........................................... 15 2.2 Running GNAT.............................................. 15 2.3 Running a Simple Ada Program..................................... 16 2.4 Running a Program with Multiple Units................................. 17 3 The GNAT Compilation Model 19 3.1 Source Representation.......................................... 19 3.2 Foreign Language Representation.................................... 20 3.2.1 Latin-1.............................................. 20 3.2.2 Other 8-Bit Codes........................................ 20 3.2.3 Wide_Character Encodings.................................... 21 3.2.4 Wide_Wide_Character Encodings................................ 22 3.3 File Naming Topics and Utilities..................................... 22 3.3.1 File Naming Rules........................................ 22 3.3.2 Using Other File Names..................................... 23 3.3.3 Alternative File Naming Schemes................................ 24 3.3.4 Handling Arbitrary File Naming Conventions with gnatname ................ 25 Arbitrary File Naming Conventions............................... 25 Running gnatname ....................................... 26 Switches for gnatname ..................................... 26 Examples of gnatname Usage................................. 27 3.3.5 File Name Krunching with gnatkr ............................... 28 About gnatkr .......................................... 28 Using gnatkr .......................................... 28 Krunching Method........................................ 29 Examples of gnatkr Usage................................... 30 3.3.6 Renaming Files with gnatchop ................................ 30 Handling Files with Multiple Units............................... 30 Operating gnatchop in Compilation Mode............................ 30 Command Line for gnatchop ................................. 31 Switches for gnatchop ..................................... 32 Examples of gnatchop Usage................................. 33 3.4 Configuration Pragmas.......................................... 33 GNAT User’s Guide for Native Platforms 5 of 332 GNAT User’s Guide for Native Platforms 23.0w 3.4.1 Handling of Configuration Pragmas............................... 35 3.4.2 The Configuration Pragmas Files................................ 35 3.5 Generating Object Files.......................................... 36 3.6 Source Dependencies........................................... 36 3.7 The Ada Library Information Files.................................... 37 3.8 Binding an Ada Program......................................... 38 3.9 GNAT and Libraries............................................ 38 3.9.1 Introduction to Libraries in GNAT................................ 38 3.9.2 General Ada Libraries...................................... 39 Building a library......................................... 39 Installing a library........................................ 40 Using a library.......................................... 41 3.9.3 Stand-alone Ada Libraries.................................... 42 Introduction to Stand-alone Libraries.............................. 42 Building a Stand-alone Library.................................. 42 Creating a Stand-alone Library to be used in a non-Ada context................ 44 Restrictions in Stand-alone Libraries............................... 45 3.9.4 Rebuilding the GNAT Run-Time Library............................ 45 3.10 Conditional Compilation......................................... 46 3.10.1 Modeling Conditional Compilation in Ada........................... 46 Use of Boolean Constants.................................... 46 Debugging - A Special Case................................... 47 Conditionalizing Declarations.................................. 48 Use of Alternative Implementations............................... 49 Preprocessing........................................... 50 3.10.2 Preprocessing with gnatprep ................................. 50 Preprocessing Symbols...................................... 51 Using gnatprep ........................................ 51 Switches for gnatprep ..................................... 51 Form of Definitions File..................................... 52 Form of Input Text for gnatprep ............................... 52 3.10.3 Integrated Preprocessing..................................... 54 3.11 Mixed Language Programming...................................... 56 3.11.1 Interfacing to C.......................................... 56 3.11.2 Calling Conventions....................................... 59 3.11.3 Building Mixed Ada and C++ Programs............................. 61 Interfacing to C++........................................ 61 Linking a Mixed C++ & Ada Program.............................. 61 A Simple Example........................................ 62 Interfacing with C++ constructors................................ 64 Interfacing with C++ at the Class Level............................. 67 3.11.4 Generating Ada Bindings for C and C++ headers........................ 71 Running the Binding Generator................................. 71 Generating Bindings for C++ Headers.............................. 72 Switches............................................. 73 3.11.5 Generating C Headers for Ada Specifications.......................... 74 Running the C Header Generator................................. 74 3.12 GNAT and Other Compilation Models.................................. 75 3.12.1 Comparison between GNAT and C/C++ Compilation Models................. 75 3.12.2 Comparison between GNAT and Conventional Ada Library Models.............. 75 3.13 Using GNAT Files with External Tools.................................. 76 3.13.1 Using Other Utility Programs with GNAT............................ 76 3.13.2 The External Symbol Naming Scheme of GNAT........................ 76 6 of 332 GNAT User’s Guide for Native Platforms GNAT User’s Guide for Native Platforms 23.0w 4 Building Executable Programs with GNAT 79 4.1 Building with gnatmake ........................................ 79 4.1.1 Running gnatmake ....................................... 80 4.1.2 Switches for gnatmake ..................................... 80 4.1.3 Mode Switches for gnatmake ................................. 85 4.1.4 Notes on the Command Line................................... 85 4.1.5 How gnatmake Works..................................... 86 4.1.6 Examples of gnatmake Usage................................. 86 4.2 Compiling with gcc ........................................... 86 4.2.1 Compiling Programs....................................... 87 4.2.2 Search Paths and the Run-Time Library (RTL)......................... 88 4.2.3 Order of Compilation Issues................................... 89 4.2.4 Examples............................................. 89 4.3 Compiler Switches............................................ 89 4.3.1 Alphabetical List of All Switches................................ 90 4.3.2 Output and Error Message Control................................ 99 4.3.3 Warning Message Control.................................... 102 4.3.4 Debugging and Assertion Control................................ 116 4.3.5 Validity Checking........................................ 117 4.3.6 Style Checking.......................................... 119 4.3.7 Run-Time Checks........................................ 125 4.3.8 Using gcc for Syntax Checking................................. 126 4.3.9 Using gcc for Semantic Checking................................ 127 4.3.10 Compiling Different Versions of Ada.............................. 127 4.3.11 Character Set Control....................................... 128 4.3.12 File Naming Control....................................... 129 4.3.13 Subprogram Inlining Control................................... 129 4.3.14 Auxiliary Output Control..................................... 130 4.3.15 Debugging Control........................................ 130 4.3.16 Exception Handling Control................................... 133 4.3.17 Units to Sources Mapping Files................................. 133 4.3.18 Code Generation Control....................................