GNAT User’s Guide for Native Platforms

GNAT, The GNU Ada Development Environment

GNAT Pro Edition

Version 22.0w

Date: Apr 11, 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 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.

• 1. About This Guide
  • 1.1. What This Guide Contains
  • 1.2. What You Should Know before Reading This Guide
  • 1.3. Related Information
  • 1.4. Conventions
• 2. Getting Started with GNAT
  • 2.1. System Requirements
  • 2.2. Running GNAT
  • 2.3. Running a Simple Ada Program
  • 2.4. Running a Program with Multiple Units
• 3. The GNAT Compilation Model
  • 3.1. Source Representation
  • 3.2. Foreign Language Representation
    • 3.2.1. Latin-1
    • 3.2.2. Other 8-Bit Codes
    • 3.2.3. Wide_Character Encodings
    • 3.2.4. Wide_Wide_Character Encodings
  • 3.3. File Naming Topics and Utilities
    • 3.3.1. File Naming Rules
    • 3.3.2. Using Other File Names
    • 3.3.3. Alternative File Naming Schemes
    • 3.3.4. Handling Arbitrary File Naming Conventions with gnatname
    • 3.3.5. File Name Krunching with gnatkr
    • 3.3.6. Renaming Files with gnatchop
  • 3.4. Configuration Pragmas
    • 3.4.1. Handling of Configuration Pragmas
    • 3.4.2. The Configuration Pragmas Files
  • 3.5. Generating Object Files
  • 3.6. Source Dependencies
  • 3.7. The Ada Library Information Files
  • 3.8. Binding an Ada Program
  • 3.9. GNAT and Libraries
    • 3.9.1. Introduction to Libraries in GNAT
    • 3.9.2. General Ada Libraries
    • 3.9.3. Stand-alone Ada Libraries
    • 3.9.4. Rebuilding the GNAT Run-Time Library
  • 3.10. Conditional Compilation
    • 3.10.1. Modeling Conditional Compilation in Ada
    • 3.10.2. Preprocessing with gnatprep
    • 3.10.3. Integrated Preprocessing
  • 3.11. Mixed Language Programming
    • 3.11.1. Interfacing to C
    • 3.11.2. Calling Conventions
    • 3.11.3. Building Mixed Ada and C++ Programs
    • 3.11.4. Generating Ada Bindings for C and C++ headers
    • 3.11.5. Generating C Headers for Ada Specifications
  • 3.12. GNAT and Other Compilation Models
    • 3.12.1. Comparison between GNAT and C/C++ Compilation Models
    • 3.12.2. Comparison between GNAT and Conventional Ada Library Models
  • 3.13. Using GNAT Files with External Tools
    • 3.13.1. Using Other Utility Programs with GNAT
    • 3.13.2. The External Symbol Naming Scheme of GNAT
• 4. Building Executable Programs with GNAT
  • 4.1. Building with gnatmake
    • 4.1.1. Running gnatmake
    • 4.1.2. Switches for gnatmake
    • 4.1.3. Mode Switches for gnatmake
    • 4.1.4. Notes on the Command Line
    • 4.1.5. How gnatmake Works
    • 4.1.6. Examples of gnatmake Usage
  • 4.2. Compiling with gcc
    • 4.2.1. Compiling Programs
    • 4.2.2. Search Paths and the Run-Time Library (RTL)
    • 4.2.3. Order of Compilation Issues
    • 4.2.4. Examples
  • 4.3. Compiler Switches
    • 4.3.1. Alphabetical List of All Switches
    • 4.3.2. Output and Error Message Control
    • 4.3.3. Warning Message Control
    • 4.3.4. Debugging and Assertion Control
    • 4.3.5. Validity Checking
    • 4.3.6. Style Checking
    • 4.3.7. Run-Time Checks
    • 4.3.8. Using gcc for Syntax Checking
    • 4.3.9. Using gcc for Semantic Checking
    • 4.3.10. Compiling Different Versions of Ada
    • 4.3.11. Character Set Control
    • 4.3.12. File Naming Control
    • 4.3.13. Subprogram Inlining Control
    • 4.3.14. Auxiliary Output Control
    • 4.3.15. Debugging Control
    • 4.3.16. Exception Handling Control
    • 4.3.17. Units to Sources Mapping Files
    • 4.3.18. Code Generation Control
  • 4.4. Linker Switches
  • 4.5. Binding with gnatbind
    • 4.5.1. Running gnatbind
    • 4.5.2. Switches for gnatbind
    • 4.5.3. Command-Line Access
    • 4.5.4. Search Paths for gnatbind
    • 4.5.5. Examples of gnatbind Usage
  • 4.6. Linking with gnatlink
    • 4.6.1. Running gnatlink
    • 4.6.2. Switches for gnatlink
  • 4.7. Using the GNU make Utility
    • 4.7.1. Using gnatmake in a Makefile
    • 4.7.2. Automatically Creating a List of Directories
    • 4.7.3. Generating the Command Line Switches
    • 4.7.4. Overcoming Command Line Length Limits
• 5. GNAT Utility Programs
  • 5.1. The File Cleanup Utility gnatclean
    • 5.1.1. Running gnatclean
    • 5.1.2. Switches for gnatclean
  • 5.2. The GNAT Library Browser gnatls
    • 5.2.1. Running gnatls
    • 5.2.2. Switches for gnatls
    • 5.2.3. Example of gnatls Usage
  • 5.3. The Coding Standard Verifier gnatcheck
  • 5.4. The GNAT Metrics Tool gnatmetric
    • 5.4.1. Output File Control
    • 5.4.2. Disable Metrics For Local Units
    • 5.4.3. Specifying a set of metrics to compute
    • 5.4.4. Other gnatmetric Switches
  • 5.5. The GNAT Pretty Printer gnatpp
    • 5.5.1. Switches for gnatpp
    • 5.5.2. Formatting Rules
  • 5.6. The Body Stub Generator gnatstub
    • 5.6.1. Running gnatstub
    • 5.6.2. Switches for gnatstub
  • 5.7. The Unit Test Generator gnattest
    • 5.7.1. Running gnattest
    • 5.7.2. Switches for gnattest in framework generation mode
    • 5.7.3. Switches for gnattest in test execution mode
    • 5.7.4. Project Attributes for gnattest
    • 5.7.5. Simple Example
    • 5.7.6. Setting Up and Tearing Down the Testing Environment
    • 5.7.7. Regenerating Tests
    • 5.7.8. Default Test Behavior
    • 5.7.9. Testing Primitive Operations of Tagged Types
    • 5.7.10. Testing Inheritance
    • 5.7.11. Tagged Type Substitutability Testing
    • 5.7.12. Testing with Contracts
    • 5.7.13. Additional Tests
    • 5.7.14. Individual Test Drivers
    • 5.7.15. Stubbing
    • 5.7.16. Integration with GNATcoverage
    • 5.7.17. Putting Tests under Version Control
    • 5.7.18. Current Limitations
  • 5.8. Translating Code Addresses into Source Locations with gnatsymbolize
    • 5.8.1. Running gnatsymbolize
    • 5.8.2. Switches for gnatsymbolize
    • 5.8.3. Requirements for Correct Operation
  • 5.9. Using Project Files with GNAT Tools
    • 5.9.1. Switches Related to Project Files
    • 5.9.2. Tool-specific packages in project files
• 6. GNAT and Program Execution
  • 6.1. Running and Debugging Ada Programs
    • 6.1.1. The GNAT Debugger GDB
    • 6.1.2. Running GDB
    • 6.1.3. Introduction to GDB Commands
    • 6.1.4. Using Ada Expressions
    • 6.1.5. Calling User-Defined Subprograms
    • 6.1.6. Using the next Command in a Function
    • 6.1.7. Stopping When Ada Exceptions Are Raised
    • 6.1.8. Ada Tasks
    • 6.1.9. Debugging Generic Units
    • 6.1.10. Remote Debugging with gdbserver
    • 6.1.11. GNAT Abnormal Termination or Failure to Terminate
    • 6.1.12. Naming Conventions for GNAT Source Files
    • 6.1.13. Getting Internal Debugging Information
    • 6.1.14. Stack Traceback
    • 6.1.15. Pretty-Printers for the GNAT runtime
  • 6.2. Profiling
    • 6.2.1. Profiling an Ada Program with gprof
  • 6.3. Improving Performance
    • 6.3.1. Performance Considerations
    • 6.3.2. Text_IO Suggestions
    • 6.3.3. Reducing Size of Executables with Unused Subprogram/Data Elimination
  • 6.4. Overflow Check Handling in GNAT
    • 6.4.1. Background
    • 6.4.2. Management of Overflows in GNAT
    • 6.4.3. Specifying the Desired Mode
    • 6.4.4. Default Settings
    • 6.4.5. Implementation Notes
  • 6.5. Performing Dimensionality Analysis in GNAT
  • 6.6. Stack Related Facilities
    • 6.6.1. Stack Overflow Checking
    • 6.6.2. Static Stack Usage Analysis
    • 6.6.3. Dynamic Stack Usage Analysis
  • 6.7. Memory Management Issues
    • 6.7.1. Some Useful Memory Pools
    • 6.7.2. The GNAT Debug Pool Facility
    • 6.7.3. The gnatmem Tool

• A. Platform-Specific Information
  • Run-Time Libraries
    • Summary of Run-Time Configurations
  • Specifying a Run-Time Library
    • Choosing the Scheduling Policy
  • GNU/Linux Topics
    • Required Packages on GNU/Linux
  • Microsoft Windows Topics
    • Using GNAT on Windows
    • Using a network installation of GNAT
    • CONSOLE and WINDOWS subsystems
    • Temporary Files
    • Disabling Command Line Argument Expansion
    • Windows Socket Timeouts
    • Mixed-Language Programming on Windows
    • Windows Specific Add-Ons
  • Mac OS Topics
    • Codesigning the Debugger
• B. Example of Binder Output
• C. Elaboration Order Handling in GNAT
  • Elaboration Code
  • Elaboration Order
  • Checking the Elaboration Order
  • Controlling the Elaboration Order in Ada
  • Controlling the Elaboration Order in GNAT
  • Mixing Elaboration Models
  • ABE Diagnostics
  • SPARK Diagnostics
  • Elaboration Circularities
  • Resolving Elaboration Circularities
  • Elaboration-related Compiler Switches
  • Summary of Procedures for Elaboration Control
  • Inspecting the Chosen Elaboration Order
• D. Inline Assembler
  • Basic Assembler Syntax
  • A Simple Example of Inline Assembler
  • Output Variables in Inline Assembler
  • Input Variables in Inline Assembler
  • Inlining Inline Assembler Code
  • Other Asm Functionality
    • The Clobber Parameter
    • The Volatile Parameter
• E. GNU Free Documentation License