GNAT User's Guide for Native Platforms GNAT User's Guide for Native Platforms , Dec 05, 2018 AdaCore Copyright c 2008-2019, 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 A Note to Readers of Previous Versions of the Manual :::::::::: 3 1.5 Conventions:::::::::::::::::::::::::::::::::::::::::::::::::::: 4 2 Getting Started with GNAT ::::::::::::::::::: 5 2.1 Running GNAT :::::::::::::::::::::::::::::::::::::::::::::::: 5 2.2 Running a Simple Ada Program :::::::::::::::::::::::::::::::: 5 2.3 Running a Program with Multiple Units :::::::::::::::::::::::: 6 2.4 Using the gnatmake Utility ::::::::::::::::::::::::::::::::::::: 7 3 The GNAT Compilation Model ::::::::::::::: 9 3.1 Source Representation:::::::::::::::::::::::::::::::::::::::::: 9 3.2 Foreign Language Representation:::::::::::::::::::::::::::::: 10 3.2.1 Latin-1::::::::::::::::::::::::::::::::::::::::::::::::::: 10 3.2.2 Other 8-Bit Codes:::::::::::::::::::::::::::::::::::::::: 10 3.2.3 Wide Character Encodings ::::::::::::::::::::::::::::::: 11 3.2.4 Wide Wide Character Encodings ::::::::::::::::::::::::: 12 3.3 File Naming Topics and Utilities :::::::::::::::::::::::::::::: 13 3.3.1 File Naming Rules ::::::::::::::::::::::::::::::::::::::: 13 3.3.2 Using Other File Names :::::::::::::::::::::::::::::::::: 14 3.3.3 Alternative File Naming Schemes ::::::::::::::::::::::::: 15 3.3.4 Handling Arbitrary File Naming Conventions with gnatname :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 17 3.3.4.1 Arbitrary File Naming Conventions :::::::::::::::::: 17 3.3.4.2 Running gnatname :::::::::::::::::::::::::::::::::: 17 3.3.4.3 Switches for gnatname ::::::::::::::::::::::::::::::: 18 3.3.4.4 Examples of gnatname Usage :::::::::::::::::::::::: 20 3.3.5 File Name Krunching with gnatkr:::::::::::::::::::::::: 20 3.3.5.1 About gnatkr ::::::::::::::::::::::::::::::::::::::: 20 3.3.5.2 Using gnatkr ::::::::::::::::::::::::::::::::::::::: 20 3.3.5.3 Krunching Method :::::::::::::::::::::::::::::::::: 21 3.3.5.4 Examples of gnatkr Usage :::::::::::::::::::::::::: 22 3.3.6 Renaming Files with gnatchop ::::::::::::::::::::::::::: 22 3.3.6.1 Handling Files with Multiple Units :::::::::::::::::: 22 3.3.6.2 Operating gnatchop in Compilation Mode ::::::::::: 23 3.3.6.3 Command Line for gnatchop :::::::::::::::::::::::: 24 3.3.6.4 Switches for gnatchop ::::::::::::::::::::::::::::::: 25 3.3.6.5 Examples of gnatchop Usage :::::::::::::::::::::::: 26 3.4 Configuration Pragmas :::::::::::::::::::::::::::::::::::::::: 26 ii 3.4.1 Handling of Configuration Pragmas::::::::::::::::::::::: 28 3.4.2 The Configuration Pragmas Files ::::::::::::::::::::::::: 29 3.5 Generating Object Files ::::::::::::::::::::::::::::::::::::::: 29 3.6 Source Dependencies :::::::::::::::::::::::::::::::::::::::::: 30 3.7 The Ada Library Information Files :::::::::::::::::::::::::::: 31 3.8 Binding an Ada Program:::::::::::::::::::::::::::::::::::::: 32 3.9 GNAT and Libraries :::::::::::::::::::::::::::::::::::::::::: 32 3.9.1 Introduction to Libraries in GNAT ::::::::::::::::::::::: 33 3.9.2 General Ada Libraries :::::::::::::::::::::::::::::::::::: 33 3.9.2.1 Building a library ::::::::::::::::::::::::::::::::::: 33 3.9.2.2 Installing a library :::::::::::::::::::::::::::::::::: 35 3.9.2.3 Using a library :::::::::::::::::::::::::::::::::::::: 36 3.9.3 Stand-alone Ada Libraries :::::::::::::::::::::::::::::::: 37 3.9.3.1 Introduction to Stand-alone Libraries :::::::::::::::: 37 3.9.3.2 Building a Stand-alone Library :::::::::::::::::::::: 37 3.9.3.3 Creating a Stand-alone Library to be used in a non-Ada context :::::::::::::::::::::::::::::::::::::::::::::::::: 39 3.9.3.4 Restrictions in Stand-alone Libraries ::::::::::::::::: 40 3.9.4 Rebuilding the GNAT Run-Time Library ::::::::::::::::: 40 3.10 Conditional Compilation ::::::::::::::::::::::::::::::::::::: 41 3.10.1 Modeling Conditional Compilation in Ada ::::::::::::::: 41 3.10.1.1 Use of Boolean Constants :::::::::::::::::::::::::: 41 3.10.1.2 Debugging - A Special Case :::::::::::::::::::::::: 42 3.10.1.3 Conditionalizing Declarations::::::::::::::::::::::: 43 3.10.1.4 Use of Alternative Implementations::::::::::::::::: 44 3.10.1.5 Preprocessing :::::::::::::::::::::::::::::::::::::: 45 3.10.2 Preprocessing with gnatprep :::::::::::::::::::::::::::: 46 3.10.2.1 Preprocessing Symbols ::::::::::::::::::::::::::::: 46 3.10.2.2 Using gnatprep :::::::::::::::::::::::::::::::::::: 46 3.10.2.3 Switches for gnatprep:::::::::::::::::::::::::::::: 47 3.10.2.4 Form of Definitions File :::::::::::::::::::::::::::: 48 3.10.2.5 Form of Input Text for gnatprep ::::::::::::::::::: 48 3.10.3 Integrated Preprocessing :::::::::::::::::::::::::::::::: 50 3.11 Mixed Language Programming ::::::::::::::::::::::::::::::: 53 3.11.1 Interfacing to C ::::::::::::::::::::::::::::::::::::::::: 53 3.11.2 Calling Conventions ::::::::::::::::::::::::::::::::::::: 56 3.11.3 Building Mixed Ada and C++ Programs :::::::::::::::: 59 3.11.3.1 Interfacing to C++::::::::::::::::::::::::::::::::: 59 3.11.3.2 Linking a Mixed C++ & Ada Program ::::::::::::: 59 3.11.3.3 A Simple Example ::::::::::::::::::::::::::::::::: 61 3.11.3.4 Interfacing with C++ constructors ::::::::::::::::: 63 3.11.3.5 Interfacing with C++ at the Class Level :::::::::::: 66 3.11.4 Generating Ada Bindings for C and C++ headers ::::::: 70 3.11.4.1 Running the Binding Generator :::::::::::::::::::: 70 3.11.4.2 Generating Bindings for C++ Headers:::::::::::::: 72 3.11.4.3 Switches ::::::::::::::::::::::::::::::::::::::::::: 73 3.11.5 Generating C Headers for Ada Specifications :::::::::::: 74 3.11.5.1 Running the C Header Generator ::::::::::::::::::: 74 iii 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 ::::::::::::::::::::::::::::::::::::::::::::::::::::: 76 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 ::::::::: 77 4 Building Executable Programs with GNAT :::::::::::::::::::::::::::::::::::::::::::::::: 78 4.1 Building with gnatmake ::::::::::::::::::::::::::::::::::::::: 78 4.1.1 Running gnatmake ::::::::::::::::::::::::::::::::::::::: 78 4.1.2 Switches for gnatmake:::::::::::::::::::::::::::::::::::: 79 4.1.3 Mode Switches for gnatmake ::::::::::::::::::::::::::::: 86 4.1.4 Notes on the Command Line ::::::::::::::::::::::::::::: 87 4.1.5 How gnatmake Works :::::::::::::::::::::::::::::::::::: 87 4.1.6 Examples of gnatmake Usage ::::::::::::::::::::::::::::: 88 4.2 Compiling with gcc ::::::::::::::::::::::::::::::::::::::::::: 88 4.2.1 Compiling Programs ::::::::::::::::::::::::::::::::::::: 89 4.2.2 Search Paths and the Run-Time Library (RTL) ::::::::::: 90 4.2.3 Order of Compilation Issues :::::::::::::::::::::::::::::: 91 4.2.4 Examples :::::::::::::::::::::::::::::::::::::::::::::::: 91 4.3 Compiler Switches :::::::::::::::::::::::::::::::::::::::::::: 91 4.3.1 Alphabetical List of All Switches ::::::::::::::::::::::::: 92 4.3.2 Output and Error Message Control :::::::::::::::::::::: 106 4.3.3 Warning Message Control ::::::::::::::::::::::::::::::: 109 4.3.4 Debugging and Assertion Control:::::::::::::::::::::::: 129 4.3.5 Validity Checking ::::::::::::::::::::::::::::::::::::::: 130 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 :::::::::::::::::::::::: 143 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 ::::::::::::::::::::::::::::::::::::: 148 4.3.16 Exception Handling Control :::::::::::::::::::::::::::: 152 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 :::::::::::::::::::::::::::::::::::::: 154 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 iv 4.5.2.3 Elaboration Control :::::::::::::::::::::::::::::::: 162 4.5.2.4 Output Control :::::::::::::::::::::::::::::::::::: 163 4.5.2.5 Dynamic Allocation Control :::::::::::::::::::::::: 163 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::::::::::::::::::::::::::::::::::::::: 166 4.6.1 Running gnatlink