“Generating Ada Bindings for C and C++ headers” in GNAT User's

341 Pages·2016·1.6 MB·English

GNAT User’s Guide for Native Platforms
GNAT User’s Guide for Native Platforms , Jan 03, 2023
AdaCore
Copyright (cid:13)c 2008-2023, 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....................................... 27
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.......................................... 30
3.9.1 Introduction to Libraries in GNAT....................... 30
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................. 38
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...................................... 43
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................... 46
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............. 57
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.................... 68
3.11.4.2 Generating Bindings for C++ Headers.............. 69
3.11.4.3 Switches........................................... 71
3.11.5 Generating C Headers for Ada Specifications ............ 71
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..................................................... 73
3.12.2 Comparison between GNAT and Conventional Ada Library
Models..................................................... 73
3.13 Using GNAT Files with External Tools....................... 74
3.13.1 Using Other Utility Programs with GNAT............... 74
3.13.2 The External Symbol Naming Scheme of GNAT......... 74
4 Building Executable Programs with GNAT
................................................ 76
4.1 Building with gnatmake....................................... 76
4.1.1 Running gnatmake....................................... 76
4.1.2 Switches for gnatmake.................................... 77
4.1.3 Mode Switches for gnatmake ............................. 84
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........................................... 87
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............................................ 90
4.3.1 Alphabetical List of All Switches......................... 90
4.3.2 Output and Error Message Control...................... 104
4.3.3 Warning Message Control............................... 108
4.3.4 Debugging and Assertion Control........................ 128
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.................................. 145
4.3.12 File Naming Control................................... 147
4.3.13 Subprogram Inlining Control........................... 147
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 ........................ 153
4.3.18 Code Generation Control............................... 153
4.4 Linker Switches.............................................. 154
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....................... 161
4.5.2.2 Binder Error Message Control...................... 161
4.5.2.3 Elaboration Control................................ 162
iv
4.5.2.4 Output Control.................................... 164
4.5.2.5 Dynamic Allocation Control........................ 164
4.5.2.6 Binding with Non-Ada Main Programs............. 165
4.5.2.7 Binding Programs with No Main Subprogram....... 166
4.5.3 Command-Line Access.................................. 166
4.5.4 Search Paths for gnatbind.............................. 166
4.5.5 Examples of gnatbind Usage............................ 167
4.6 Linking with gnatlink....................................... 167
4.6.1 Running gnatlink...................................... 168
4.6.2 Switches for gnatlink .................................. 168
4.7 Using the GNU make Utility ................................. 170
4.7.1 Using gnatmake in a Makefile........................... 170
4.7.2 Automatically Creating a List of Directories............. 172
4.7.3 Generating the Command Line Switches................. 173
4.7.4 Overcoming Command Line Length Limits.............. 174
5 GNAT Utility Programs..................... 175
5.1 The File Cleanup Utility gnatclean.......................... 175
5.1.1 Running gnatclean..................................... 175
5.1.2 Switches for gnatclean................................. 175
5.2 The GNAT Library Browser gnatls.......................... 177
5.2.1 Running gnatls........................................ 177
5.2.2 Switches for gnatls..................................... 178
5.2.3 Example of gnatls Usage............................... 179
6 GNAT and Program Execution............. 181
6.1 Running and Debugging Ada Programs ...................... 181
6.1.1 The GNAT Debugger GDB ............................. 181
6.1.2 Running GDB.......................................... 182
6.1.3 Introduction to GDB Commands........................ 182
6.1.4 Using Ada Expressions.................................. 185
6.1.5 Calling User-Defined Subprograms....................... 185
6.1.6 Using the ‘next’ Command in a Function................ 186
6.1.7 Stopping When Ada Exceptions Are Raised ............. 186
6.1.8 Ada Tasks.............................................. 187
6.1.9 Debugging Generic Units................................ 187
6.1.10 Remote Debugging with gdbserver ..................... 188
6.1.11 GNAT Abnormal Termination or Failure to Terminate.. 189
6.1.12 Naming Conventions for GNAT Source Files............ 190
6.1.13 Getting Internal Debugging Information................ 190
6.1.14 Stack Traceback ....................................... 191
6.1.14.1 Non-Symbolic Traceback.......................... 191
6.1.14.2 Symbolic Traceback............................... 196
6.1.15 Pretty-Printers for the GNAT runtime ................. 198
6.2 Profiling..................................................... 199
6.2.1 Profiling an Ada Program with gprof.................... 199
6.2.1.1 Compilation for profiling........................... 199
6.2.1.2 Program execution................................. 200
v
6.2.1.3 Running gprof...................................... 200
6.2.1.4 Interpretation of profiling results ................... 201
6.3 Improving Performance...................................... 201
6.3.1 Performance Considerations............................. 201
6.3.1.1 Controlling Run-Time Checks...................... 202
6.3.1.2 Use of Restrictions................................. 202
6.3.1.3 Optimization Levels................................ 202
6.3.1.4 Debugging Optimized Code ........................ 204
6.3.1.5 Inlining of Subprograms............................ 205
6.3.1.6 Floating Point Operations.......................... 207
6.3.1.7 Vectorization of loops.............................. 207
6.3.1.8 Other Optimization Switches....................... 209
6.3.1.9 Optimization and Strict Aliasing ................... 209
6.3.1.10 Aliased Variables and Optimization................ 213
6.3.1.11 Atomic Variables and Optimization................ 213
6.3.1.12 Passive Task Optimization ........................ 214
6.3.2 Text_IO Suggestions.................................... 215
6.3.3 Reducing Size of Executables with Unused Subprogram/Data
Elimination ............................................... 215
6.3.3.1 About unused subprogram/data elimination........ 215
6.3.3.2 Compilation options................................ 215
6.3.3.3 Example of unused subprogram/data elimination ... 216
6.4 Overflow Check Handling in GNAT.......................... 217
6.4.1 Background............................................. 217
6.4.2 Management of Overflows in GNAT..................... 218
6.4.3 Specifying the Desired Mode............................ 220
6.4.4 Default Settings......................................... 221
6.4.5 Implementation Notes................................... 221
6.5 Performing Dimensionality Analysis in GNAT................ 222
6.6 Stack Related Facilities...................................... 226
6.6.1 Stack Overflow Checking................................ 226
6.6.2 Static Stack Usage Analysis............................. 226
6.6.3 Dynamic Stack Usage Analysis.......................... 227
6.7 Memory Management Issues ................................. 228
6.7.1 Some Useful Memory Pools.............................. 228
6.7.2 The GNAT Debug Pool Facility......................... 229
7 Platform-Specific Information............... 232
7.1 Run-Time Libraries.......................................... 232
7.1.1 Summary of Run-Time Configurations................... 232
7.2 Specifying a Run-Time Library............................... 232
7.2.1 Choosing the Scheduling Policy.......................... 233
7.3 GNU/Linux Topics .......................................... 234
7.3.1 Required Packages on GNU/Linux ...................... 234
7.3.2 A GNU/Linux Debug Quirk............................. 234
7.4 Microsoft Windows Topics................................... 235
7.4.1 Using GNAT on Windows............................... 235
7.4.2 Using a network installation of GNAT................... 236
vi
7.4.3 CONSOLE and WINDOWS subsystems................. 236
7.4.4 Temporary Files ........................................ 236
7.4.5 Disabling Command Line Argument Expansion.......... 236
7.4.6 Windows Socket Timeouts .............................. 237
7.4.7 Mixed-Language Programming on Windows............. 238
7.4.7.1 Windows Calling Conventions...................... 239
7.4.7.2 C Calling Convention............................... 239
7.4.7.3 Stdcall Calling Convention........................ 239
7.4.7.4 Win32 Calling Convention.......................... 240
7.4.7.5 DLL Calling Convention............................. 240
7.4.7.6 Introduction to Dynamic Link Libraries (DLLs)..... 241
7.4.7.7 Using DLLs with GNAT............................ 242
7.4.7.8 Creating an Ada Spec for the DLL Services......... 242
7.4.7.9 Creating an Import Library ........................ 243
7.4.7.10 Building DLLs with GNAT Project files........... 245
7.4.7.11 Building DLLs with GNAT........................ 245
7.4.7.12 Building DLLs with gnatdll ....................... 245
7.4.7.13 Limitations When Using Ada DLLs from Ada..... 246
7.4.7.14 Exporting Ada Entities............................ 246
7.4.7.15 Ada DLLs and Elaboration........................ 248
7.4.7.16 Ada DLLs and Finalization........................ 248
7.4.7.17 Creating a Spec for Ada DLLs..................... 249
7.4.7.18 Creating the Definition File....................... 249
7.4.7.19 Using gnatdll.................................... 249
7.4.7.20 GNAT and Windows Resources ................... 253
7.4.7.21 Building Resources................................ 254
7.4.7.22 Compiling Resources.............................. 254
7.4.7.23 Using Resources................................... 254
7.4.7.24 Using GNAT DLLs from Microsoft Visual Studio
Applications............................................ 254
7.4.7.25 Debugging a DLL................................. 255
7.4.7.26 Program and DLL Both Built with GCC/GNAT... 255
7.4.7.27 Program Built with Foreign Tools and DLL Built with
GCC/GNAT........................................... 256
7.4.7.28 Setting Stack Size from gnatlink................. 257
7.4.7.29 Setting Heap Size from gnatlink.................. 258
7.4.8 Windows Specific Add-Ons.............................. 258
7.4.8.1 Win32Ada......................................... 258
7.4.8.2 wPOSIX........................................... 258
7.5 Mac OS Topics .............................................. 259
7.5.1 Codesigning the Debugger............................... 259
8 Example of Binder Output File............. 260
vii
9 Elaboration Order Handling in GNAT ..... 276
9.1 Elaboration Code............................................ 276
9.2 Elaboration Order........................................... 277
9.3 Checking the Elaboration Order.............................. 279
9.4 Controlling the Elaboration Order in Ada.................... 280
9.5 Controlling the Elaboration Order in GNAT.................. 284
9.6 Mixing Elaboration Models .................................. 285
9.7 ABE Diagnostics............................................. 285
9.8 SPARK Diagnostics.......................................... 287
9.9 Elaboration Circularities..................................... 287
9.10 Resolving Elaboration Circularities.......................... 289
9.11 Elaboration-related Compiler Switches...................... 291
9.12 Summary of Procedures for Elaboration Control............. 293
9.13 Inspecting the Chosen Elaboration Order.................... 294
10 Inline Assembler............................ 297
10.1 Basic Assembler Syntax..................................... 297
10.2 A Simple Example of Inline Assembler...................... 298
10.3 Output Variables in Inline Assembler........................ 299
10.4 Input Variables in Inline Assembler ......................... 303
10.5 Inlining Inline Assembler Code.............................. 304
10.6 Other Asm Functionality .................................... 305
10.6.1 The Clobber Parameter................................ 305
10.6.2 The Volatile Parameter .............................. 306
11 GNU Free Documentation License ........ 307
Index.............................................. 314
1
‘GNAT, The GNU Ada Development Environment’
GCC version 13.0.1
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 User’s Guide for Native Platforms”, and with no Back-Cover Texts. A copy of the
license is included in the section entitled [GNU Free Documentation License], page 306.
Chapter 1: About This Guide 2
1 About This Guide
This guide describes the use of GNAT, a compiler and software development toolset for the
full Ada programming language. It documents the features of the compiler and tools, and
explains how to use them to build Ada applications.
GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, and it may also be invoked
in Ada 83 compatibility mode. By default, GNAT assumes Ada 2012, but you can override
withacompilerswitch([CompilingDifferentVersionsofAda],page143)toexplicitlyspecify
the language version. Throughout this manual, references to ‘Ada’ without a year suffix
apply to all Ada versions of the language, starting with Ada 95.
1.1 What This Guide Contains
This guide contains the following chapters:
* [Getting Started with GNAT], page 3 describes how to get started compiling and run-
ning Ada programs with the GNAT Ada programming environment.
* [The GNAT Compilation Model], page 6 describes the compilation model used by
GNAT.
* [Building Executable Programs with GNAT], page 75 describes how to use the main
GNATtoolstobuildexecutableprograms, anditalsogivesexamplesofusingtheGNU
make utility with GNAT.
* [GNAT Utility Programs], page 174 explains the various utility programs that are
included in the GNAT environment
* [GNATandProgramExecution],page180coversanumberoftopicsrelatedtorunning,
debugging, and tuning the performace of programs developed with GNAT
Appendices cover several additional topics:
* [Platform-Specific Information], page 231 describes the different run-time library im-
plementations and also presents information on how to use GNAT on several specific
platforms
* [Example of Binder Output File], page 259 shows the source code for the binder output
file for a sample program.
* [Elaboration Order Handling in GNAT], page 275 describes how GNAT helps you deal
with elaboration order issues.
* [Inline Assembler], page 296 shows how to use the inline assembly facility in an Ada
program.
1.2 What You Should Know before Reading This Guide
This guide assumes a basic familiarity with the Ada 95 language, as described in the In-
ternational Standard ANSI/ISO/IEC-8652:1995, January 1995. Reference manuals for Ada
95, Ada 2005, and Ada 2012 are included in the GNAT documentation package.