GNAT User’s Guide for Native Platforms

GNAT, The GNU Ada Development Environment

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
• 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

• 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
    • A GNU/Linux Debug Quirk
  • 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
  • Preamble
  • 1. APPLICABILITY AND DEFINITIONS
  • 2. VERBATIM COPYING
  • 3. COPYING IN QUANTITY
  • 4. MODIFICATIONS
  • 5. COMBINING DOCUMENTS
  • 6. COLLECTIONS OF DOCUMENTS
  • 7. AGGREGATION WITH INDEPENDENT WORKS
  • 8. TRANSLATION
  • 9. TERMINATION
  • 10. FUTURE REVISIONS OF THIS LICENSE
  • 11. RELICENSING
  • ADDENDUM: How to use this License for your documents