GNAT User's Guide for Native Platforms GNAT User's Guide for Native Platforms , November 18, 2015 AdaCore Copyright c 2008-2016, 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 ::::::::::::::::::::::: 32 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 :::::::::::::::::::::::::::::::::::::: 35 3.9.3 Stand-alone Ada Libraries :::::::::::::::::::::::::::::::: 36 3.9.3.1 Introduction to Stand-alone Libraries :::::::::::::::: 36 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 :::::::::::::::::::::::::::::::::::::::::::::::::: 38 3.9.3.4 Restrictions in Stand-alone Libraries ::::::::::::::::: 40 3.9.4 Rebuilding the GNAT Run-Time Library ::::::::::::::::: 40 3.10 Conditional Compilation ::::::::::::::::::::::::::::::::::::: 40 3.10.1 Modeling Conditional Compilation in Ada ::::::::::::::: 40 3.10.1.1 Use of Boolean Constants :::::::::::::::::::::::::: 41 3.10.1.2 Debugging - A Special Case :::::::::::::::::::::::: 41 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 :::::::::::::::::::::::::::::: 46 3.10.2.4 Form of Definitions File :::::::::::::::::::::::::::: 47 3.10.2.5 Form of Input Text for gnatprep:::::::::::::::::::: 48 3.10.3 Integrated Preprocessing :::::::::::::::::::::::::::::::: 49 3.11 Mixed Language Programming ::::::::::::::::::::::::::::::: 52 3.11.1 Interfacing to C ::::::::::::::::::::::::::::::::::::::::: 52 3.11.2 Calling Conventions ::::::::::::::::::::::::::::::::::::: 55 3.11.3 Building Mixed Ada and C++ Programs :::::::::::::::: 57 3.11.3.1 Interfacing to C++::::::::::::::::::::::::::::::::: 58 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 ::::::::::::::::: 62 3.11.3.5 Interfacing with C++ at the Class Level :::::::::::: 64 3.11.4 Generating Ada Bindings for C and C++ headers ::::::: 69 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 ::::::::::::::::::: 73 iii 3.12 GNAT and Other Compilation Models ::::::::::::::::::::::: 74 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 :::::::::::::::::::::::::::::::::::: 87 4.1.6 Examples of gnatmake Usage ::::::::::::::::::::::::::::: 87 4.2 Compiling with gcc ::::::::::::::::::::::::::::::::::::::::::: 88 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 :::::::::::::::::::::::::::::::::::::::::::: 91 4.3.1 Alphabetical List of All Switches ::::::::::::::::::::::::: 91 4.3.2 Output and Error Message Control :::::::::::::::::::::: 104 4.3.3 Warning Message Control ::::::::::::::::::::::::::::::: 108 4.3.4 Debugging and Assertion Control:::::::::::::::::::::::: 126 4.3.5 Validity Checking ::::::::::::::::::::::::::::::::::::::: 127 4.3.6 Style Checking :::::::::::::::::::::::::::::::::::::::::: 130 4.3.7 Run-Time Checks ::::::::::::::::::::::::::::::::::::::: 137 4.3.8 Using gcc for Syntax Checking :::::::::::::::::::::::::: 139 4.3.9 Using gcc for Semantic Checking :::::::::::::::::::::::: 139 4.3.10 Compiling Different Versions of Ada:::::::::::::::::::: 140 4.3.11 Character Set Control:::::::::::::::::::::::::::::::::: 141 4.3.12 File Naming Control ::::::::::::::::::::::::::::::::::: 143 4.3.13 Subprogram Inlining Control ::::::::::::::::::::::::::: 143 4.3.14 Auxiliary Output Control :::::::::::::::::::::::::::::: 144 4.3.15 Debugging Control ::::::::::::::::::::::::::::::::::::: 144 4.3.16 Exception Handling Control :::::::::::::::::::::::::::: 148 4.3.17 Units to Sources Mapping Files :::::::::::::::::::::::: 149 4.3.18 Code Generation Control::::::::::::::::::::::::::::::: 149 4.4 Binding with gnatbind ::::::::::::::::::::::::::::::::::::::: 150 4.4.1 Running gnatbind ::::::::::::::::::::::::::::::::::::::: 150 4.4.2 Switches for gnatbind ::::::::::::::::::::::::::::::::::: 151 4.4.2.1 Consistency-Checking Modes ::::::::::::::::::::::: 156 4.4.2.2 Binder Error Message Control :::::::::::::::::::::: 157 4.4.2.3 Elaboration Control :::::::::::::::::::::::::::::::: 158 iv 4.4.2.4 Output Control :::::::::::::::::::::::::::::::::::: 158 4.4.2.5 Dynamic Allocation Control :::::::::::::::::::::::: 159 4.4.2.6 Binding with Non-Ada Main Programs ::::::::::::: 159 4.4.2.7 Binding Programs with No Main Subprogram::::::: 160 4.4.3 Command-Line Access :::::::::::::::::::::::::::::::::: 160 4.4.4 Search Paths for gnatbind ::::::::::::::::::::::::::::::: 161 4.4.5 Examples of gnatbind Usage :::::::::::::::::::::::::::: 161 4.5 Linking with gnatlink :::::::::::::::::::::::::::::::::::::::: 162 4.5.1 Running gnatlink ::::::::::::::::::::::::::::::::::::::: 162 4.5.2