GNAT User's Guide for Native Platforms GNAT User's Guide for Native Platforms , Dec 11, 2020 AdaCore Copyright c 2008-2021, Free Software Foundation i Table of Contents 1 About This Guide :::::::::::::::::::::::::::::: 2 1.1 What This Guide Contains ::::::::::::::::::::::::::::::::::::: 2 1.2 What You Should Know before Reading This Guide :::::::::::: 2 1.3 Related Information :::::::::::::::::::::::::::::::::::::::::::: 3 1.4 Conventions:::::::::::::::::::::::::::::::::::::::::::::::::::: 3 2 Getting Started with GNAT ::::::::::::::::::: 4 2.1 System Requirements :::::::::::::::::::::::::::::::::::::::::: 4 2.2 Running GNAT :::::::::::::::::::::::::::::::::::::::::::::::: 4 2.3 Running a Simple Ada Program :::::::::::::::::::::::::::::::: 4 2.4 Running a Program with Multiple Units :::::::::::::::::::::::: 5 3 The GNAT Compilation Model ::::::::::::::: 7 3.1 Source Representation:::::::::::::::::::::::::::::::::::::::::: 7 3.2 Foreign Language Representation ::::::::::::::::::::::::::::::: 8 3.2.1 Latin-1:::::::::::::::::::::::::::::::::::::::::::::::::::: 8 3.2.2 Other 8-Bit Codes::::::::::::::::::::::::::::::::::::::::: 8 3.2.3 Wide Character Encodings :::::::::::::::::::::::::::::::: 9 3.2.4 Wide Wide Character Encodings ::::::::::::::::::::::::: 10 3.3 File Naming Topics and Utilities :::::::::::::::::::::::::::::: 11 3.3.1 File Naming Rules ::::::::::::::::::::::::::::::::::::::: 11 3.3.2 Using Other File Names :::::::::::::::::::::::::::::::::: 12 3.3.3 Alternative File Naming Schemes ::::::::::::::::::::::::: 13 3.3.4 Handling Arbitrary File Naming Conventions with gnatname :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 15 3.3.4.1 Arbitrary File Naming Conventions :::::::::::::::::: 15 3.3.4.2 Running gnatname :::::::::::::::::::::::::::::::::: 15 3.3.4.3 Switches for gnatname ::::::::::::::::::::::::::::::: 16 3.3.4.4 Examples of gnatname Usage :::::::::::::::::::::::: 18 3.3.5 File Name Krunching with gnatkr:::::::::::::::::::::::: 18 3.3.5.1 About gnatkr ::::::::::::::::::::::::::::::::::::::: 18 3.3.5.2 Using gnatkr ::::::::::::::::::::::::::::::::::::::: 18 3.3.5.3 Krunching Method :::::::::::::::::::::::::::::::::: 19 3.3.5.4 Examples of gnatkr Usage :::::::::::::::::::::::::: 20 3.3.6 Renaming Files with gnatchop ::::::::::::::::::::::::::: 20 3.3.6.1 Handling Files with Multiple Units :::::::::::::::::: 20 3.3.6.2 Operating gnatchop in Compilation Mode ::::::::::: 21 3.3.6.3 Command Line for gnatchop :::::::::::::::::::::::: 22 3.3.6.4 Switches for gnatchop ::::::::::::::::::::::::::::::: 23 3.3.6.5 Examples of gnatchop Usage :::::::::::::::::::::::: 24 3.4 Configuration Pragmas :::::::::::::::::::::::::::::::::::::::: 24 3.4.1 Handling of Configuration Pragmas::::::::::::::::::::::: 26 ii 3.4.2 The Configuration Pragmas Files ::::::::::::::::::::::::: 27 3.5 Generating Object Files ::::::::::::::::::::::::::::::::::::::: 28 3.6 Source Dependencies :::::::::::::::::::::::::::::::::::::::::: 28 3.7 The Ada Library Information Files :::::::::::::::::::::::::::: 29 3.8 Binding an Ada Program:::::::::::::::::::::::::::::::::::::: 30 3.9 GNAT and Libraries :::::::::::::::::::::::::::::::::::::::::: 31 3.9.1 Introduction to Libraries in GNAT ::::::::::::::::::::::: 31 3.9.2 General Ada Libraries :::::::::::::::::::::::::::::::::::: 31 3.9.2.1 Building a library ::::::::::::::::::::::::::::::::::: 31 3.9.2.2 Installing a library :::::::::::::::::::::::::::::::::: 33 3.9.2.3 Using a library :::::::::::::::::::::::::::::::::::::: 34 3.9.3 Stand-alone Ada Libraries :::::::::::::::::::::::::::::::: 35 3.9.3.1 Introduction to Stand-alone Libraries :::::::::::::::: 35 3.9.3.2 Building a Stand-alone Library :::::::::::::::::::::: 35 3.9.3.3 Creating a Stand-alone Library to be used in a non-Ada context :::::::::::::::::::::::::::::::::::::::::::::::::: 37 3.9.3.4 Restrictions in Stand-alone Libraries ::::::::::::::::: 38 3.9.4 Rebuilding the GNAT Run-Time Library ::::::::::::::::: 39 3.10 Conditional Compilation ::::::::::::::::::::::::::::::::::::: 39 3.10.1 Modeling Conditional Compilation in Ada ::::::::::::::: 39 3.10.1.1 Use of Boolean Constants :::::::::::::::::::::::::: 39 3.10.1.2 Debugging - A Special Case :::::::::::::::::::::::: 40 3.10.1.3 Conditionalizing Declarations::::::::::::::::::::::: 41 3.10.1.4 Use of Alternative Implementations::::::::::::::::: 42 3.10.1.5 Preprocessing :::::::::::::::::::::::::::::::::::::: 44 3.10.2 Preprocessing with gnatprep :::::::::::::::::::::::::::: 44 3.10.2.1 Preprocessing Symbols ::::::::::::::::::::::::::::: 44 3.10.2.2 Using gnatprep :::::::::::::::::::::::::::::::::::: 44 3.10.2.3 Switches for gnatprep:::::::::::::::::::::::::::::: 45 3.10.2.4 Form of Definitions File :::::::::::::::::::::::::::: 46 3.10.2.5 Form of Input Text for gnatprep ::::::::::::::::::: 47 3.10.3 Integrated Preprocessing :::::::::::::::::::::::::::::::: 48 3.11 Mixed Language Programming ::::::::::::::::::::::::::::::: 51 3.11.1 Interfacing to C ::::::::::::::::::::::::::::::::::::::::: 51 3.11.2 Calling Conventions ::::::::::::::::::::::::::::::::::::: 54 3.11.3 Building Mixed Ada and C++ Programs :::::::::::::::: 57 3.11.3.1 Interfacing to C++::::::::::::::::::::::::::::::::: 57 3.11.3.2 Linking a Mixed C++ & Ada Program ::::::::::::: 58 3.11.3.3 A Simple Example ::::::::::::::::::::::::::::::::: 59 3.11.3.4 Interfacing with C++ constructors ::::::::::::::::: 61 3.11.3.5 Interfacing with C++ at the Class Level :::::::::::: 64 3.11.4 Generating Ada Bindings for C and C++ headers ::::::: 68 3.11.4.1 Running the Binding Generator :::::::::::::::::::: 69 3.11.4.2 Generating Bindings for C++ Headers:::::::::::::: 70 3.11.4.3 Switches ::::::::::::::::::::::::::::::::::::::::::: 72 3.11.5 Generating C Headers for Ada Specifications :::::::::::: 72 3.11.5.1 Running the C Header Generator ::::::::::::::::::: 72 3.12 GNAT and Other Compilation Models ::::::::::::::::::::::: 73 iii 3.12.1 Comparison between GNAT and C/C++ Compilation Models ::::::::::::::::::::::::::::::::::::::::::::::::::::: 74 3.12.2 Comparison between GNAT and Conventional Ada Library Models ::::::::::::::::::::::::::::::::::::::::::::::::::::: 74 3.13 Using GNAT Files with External Tools ::::::::::::::::::::::: 75 3.13.1 Using Other Utility Programs with GNAT::::::::::::::: 75 3.13.2 The External Symbol Naming Scheme of GNAT ::::::::: 75 4 Building Executable Programs with GNAT :::::::::::::::::::::::::::::::::::::::::::::::: 77 4.1 Building with gnatmake ::::::::::::::::::::::::::::::::::::::: 77 4.1.1 Running gnatmake ::::::::::::::::::::::::::::::::::::::: 77 4.1.2 Switches for gnatmake:::::::::::::::::::::::::::::::::::: 78 4.1.3 Mode Switches for gnatmake ::::::::::::::::::::::::::::: 85 4.1.4 Notes on the Command Line ::::::::::::::::::::::::::::: 86 4.1.5 How gnatmake Works :::::::::::::::::::::::::::::::::::: 86 4.1.6 Examples of gnatmake Usage ::::::::::::::::::::::::::::: 87 4.2 Compiling with gcc ::::::::::::::::::::::::::::::::::::::::::: 87 4.2.1 Compiling Programs ::::::::::::::::::::::::::::::::::::: 88 4.2.2 Search Paths and the Run-Time Library (RTL) ::::::::::: 89 4.2.3 Order of Compilation Issues :::::::::::::::::::::::::::::: 90 4.2.4 Examples :::::::::::::::::::::::::::::::::::::::::::::::: 90 4.3 Compiler Switches :::::::::::::::::::::::::::::::::::::::::::: 90 4.3.1 Alphabetical List of All Switches ::::::::::::::::::::::::: 91 4.3.2 Output and Error Message Control :::::::::::::::::::::: 105 4.3.3 Warning Message Control ::::::::::::::::::::::::::::::: 108 4.3.4 Debugging and Assertion Control:::::::::::::::::::::::: 128 4.3.5 Validity Checking ::::::::::::::::::::::::::::::::::::::: 129 4.3.6 Style Checking :::::::::::::::::::::::::::::::::::::::::: 133 4.3.7 Run-Time Checks ::::::::::::::::::::::::::::::::::::::: 140 4.3.8 Using gcc for Syntax Checking :::::::::::::::::::::::::: 142 4.3.9 Using gcc for Semantic Checking :::::::::::::::::::::::: 142 4.3.10 Compiling Different Versions of Ada:::::::::::::::::::: 143 4.3.11 Character Set Control:::::::::::::::::::::::::::::::::: 144 4.3.12 File Naming Control ::::::::::::::::::::::::::::::::::: 146 4.3.13 Subprogram Inlining Control ::::::::::::::::::::::::::: 146 4.3.14 Auxiliary Output Control :::::::::::::::::::::::::::::: 147 4.3.15 Debugging Control ::::::::::::::::::::::::::::::::::::: 147 4.3.16 Exception Handling Control :::::::::::::::::::::::::::: 151 4.3.17 Units to Sources Mapping Files :::::::::::::::::::::::: 152 4.3.18 Code Generation Control::::::::::::::::::::::::::::::: 153 4.4 Linker Switches :::::::::::::::::::::::::::::::::::::::::::::: 153 4.5 Binding with gnatbind :::::::::::::::::::::::::::::::::::::: 153 4.5.1 Running gnatbind :::::::::::::::::::::::::::::::::::::: 154 4.5.2 Switches for gnatbind :::::::::::::::::::::::::::::::::: 155 4.5.2.1 Consistency-Checking Modes ::::::::::::::::::::::: 160 4.5.2.2 Binder Error Message Control :::::::::::::::::::::: 161 4.5.2.3 Elaboration Control :::::::::::::::::::::::::::::::: 162 iv 4.5.2.4 Output Control :::::::::::::::::::::::::::::::::::: 163 4.5.2.5 Dynamic Allocation Control :::::::::::::::::::::::: 164 4.5.2.6 Binding with Non-Ada Main Programs ::::::::::::: 164 4.5.2.7 Binding Programs with No Main Subprogram::::::: 165 4.5.3 Command-Line Access :::::::::::::::::::::::::::::::::: 165 4.5.4 Search Paths for gnatbind :::::::::::::::::::::::::::::: 165 4.5.5 Examples of gnatbind Usage :::::::::::::::::::::::::::: 166 4.6 Linking with gnatlink::::::::::::::::::::::::::::::::::::::: 167 4.6.1 Running gnatlink :::::::::::::::::::::::::::::::::::::: 167 4.6.2 Switches for gnatlink