GNAT User's Guide

GNAT User's Guide

GNAT User's Guide

GNAT, The GNU Ada Compiler
GCC version 4.6.4

AdaCore

• About This Guide
• Getting Started with GNAT
• The GNAT Compilation Model
• Compiling Using gcc
• Binding Using gnatbind
• Linking Using gnatlink
• The GNAT Make Program gnatmake
• Improving Performance
• Renaming Files Using gnatchop
• Configuration Pragmas
• Handling Arbitrary File Naming Conventions Using gnatname
• GNAT Project Manager
• Tools Supporting Project Files
• The Cross-Referencing Tools gnatxref and gnatfind
• The GNAT Pretty-Printer gnatpp
• The GNAT Metric Tool gnatmetric
• File Name Krunching Using gnatkr
• Preprocessing Using gnatprep
• The GNAT Library Browser gnatls
• Cleaning Up Using gnatclean
• GNAT and Libraries
• Using the GNU make Utility
• Memory Management Issues
• Stack Related Facilities
• Verifying Properties Using gnatcheck
• Creating Sample Bodies Using gnatstub
• Generating Ada Bindings for C and C++ headers
• Other Utility Programs
• Running and Debugging Ada Programs
• Code Coverage and Profiling
• Platform-Specific Information for the Run-Time Libraries
• Example of Binder Output File
• Elaboration Order Handling in GNAT
• Conditional Compilation
• Inline Assembler
• Compatibility and Porting Guide
• Microsoft Windows Topics
• GNU Free Documentation License
• Index

--- The Detailed Node Listing ---

About This Guide

• What This Guide Contains
• What You Should Know before Reading This Guide
• Related Information
• Conventions

Getting Started with GNAT

• Running GNAT
• Running a Simple Ada Program
• Running a Program with Multiple Units
• Using the gnatmake Utility
• Introduction to GPS

The GNAT Compilation Model

• Source Representation
• Foreign Language Representation
• File Naming Rules
• Using Other File Names
• Alternative File Naming Schemes
• Generating Object Files
• Source Dependencies
• The Ada Library Information Files
• Binding an Ada Program
• Mixed Language Programming
• Building Mixed Ada & C++ Programs
• Comparison between GNAT and C/C++ Compilation Models
• Comparison between GNAT and Conventional Ada Library Models

Foreign Language Representation

• Latin-1
• Other 8-Bit Codes
• Wide Character Encodings

Compiling Ada Programs With gcc

• Compiling Programs
• Switches for gcc
• Search Paths and the Run-Time Library (RTL)
• Order of Compilation Issues
• Examples

Switches for gcc

• Output and Error Message Control
• Warning Message Control
• Debugging and Assertion Control
• Validity Checking
• Style Checking
• Run-Time Checks
• Using gcc for Syntax Checking
• Using gcc for Semantic Checking
• Compiling Different Versions of Ada
• Character Set Control
• File Naming Control
• Subprogram Inlining Control
• Auxiliary Output Control
• Debugging Control
• Exception Handling Control
• Units to Sources Mapping Files
• Integrated Preprocessing

Binding Ada Programs With gnatbind

• Running gnatbind
• Switches for gnatbind
• Command-Line Access
• Search Paths for gnatbind
• Examples of gnatbind Usage

Switches for gnatbind

• Consistency-Checking Modes
• Binder Error Message Control
• Elaboration Control
• Output Control
• Binding with Non-Ada Main Programs
• Binding Programs with No Main Subprogram

Linking Using gnatlink

• Running gnatlink
• Switches for gnatlink

The GNAT Make Program gnatmake

• Running gnatmake
• Switches for gnatmake
• Mode Switches for gnatmake
• Notes on the Command Line
• How gnatmake Works
• Examples of gnatmake Usage

Improving Performance

• Performance Considerations
• Text_IO Suggestions
• Reducing Size of Ada Executables with gnatelim
• Reducing Size of Executables with unused subprogram/data elimination

Performance Considerations

• Controlling Run-Time Checks
• Use of Restrictions
• Optimization Levels
• Debugging Optimized Code
• Inlining of Subprograms
• Other Optimization Switches
• Optimization and Strict Aliasing

Reducing Size of Ada Executables with gnatelim

• About gnatelim
• Running gnatelim
• Processing Precompiled Libraries
• Correcting the List of Eliminate Pragmas
• Making Your Executables Smaller
• Summary of the gnatelim Usage Cycle

Reducing Size of Executables with unused subprogram/data elimination

• About unused subprogram/data elimination
• Compilation options

Renaming Files Using gnatchop

• Handling Files with Multiple Units
• Operating gnatchop in Compilation Mode
• Command Line for gnatchop
• Switches for gnatchop
• Examples of gnatchop Usage

Configuration Pragmas

• Handling of Configuration Pragmas
• The Configuration Pragmas Files

Handling Arbitrary File Naming Conventions Using gnatname

• Arbitrary File Naming Conventions
• Running gnatname
• Switches for gnatname
• Examples of gnatname Usage

The Cross-Referencing Tools gnatxref and gnatfind

• Switches for gnatxref
• Switches for gnatfind
• Project Files for gnatxref and gnatfind
• Regular Expressions in gnatfind and gnatxref
• Examples of gnatxref Usage
• Examples of gnatfind Usage

The GNAT Pretty-Printer gnatpp

• Switches for gnatpp
• Formatting Rules

The GNAT Metrics Tool gnatmetric

• Switches for gnatmetric

File Name Krunching Using gnatkr

• About gnatkr
• Using gnatkr
• Krunching Method
• Examples of gnatkr Usage

Preprocessing Using gnatprep

• Preprocessing Symbols
• Using gnatprep
• Switches for gnatprep
• Form of Definitions File
• Form of Input Text for gnatprep

The GNAT Library Browser gnatls

• Running gnatls
• Switches for gnatls
• Examples of gnatls Usage

Cleaning Up Using gnatclean

• Running gnatclean
• Switches for gnatclean

GNAT and Libraries

• Introduction to Libraries in GNAT
• General Ada Libraries
• Stand-alone Ada Libraries
• Rebuilding the GNAT Run-Time Library

Using the GNU make Utility

• Using gnatmake in a Makefile
• Automatically Creating a List of Directories
• Generating the Command Line Switches
• Overcoming Command Line Length Limits

Memory Management Issues

• Some Useful Memory Pools
• The GNAT Debug Pool Facility
• The gnatmem Tool

Stack Related Facilities

• Stack Overflow Checking
• Static Stack Usage Analysis
• Dynamic Stack Usage Analysis

Some Useful Memory Pools

The GNAT Debug Pool Facility

The gnatmem Tool

• Running gnatmem
• Switches for gnatmem
• Example of gnatmem Usage

Verifying Properties Using gnatcheck

Sample Bodies Using gnatstub

• Running gnatstub
• Switches for gnatstub

Other Utility Programs

• Using Other Utility Programs with GNAT
• The External Symbol Naming Scheme of GNAT
• Converting Ada Files to html with gnathtml

Code Coverage and Profiling

• Code Coverage of Ada Programs using gcov
• Profiling an Ada Program using gprof

Running and Debugging Ada Programs

• The GNAT Debugger GDB
• Running GDB
• Introduction to GDB Commands
• Using Ada Expressions
• Calling User-Defined Subprograms
• Using the Next Command in a Function
• Ada Exceptions
• Ada Tasks
• Debugging Generic Units
• Remote Debugging using gdbserver
• GNAT Abnormal Termination or Failure to Terminate
• Naming Conventions for GNAT Source Files
• Getting Internal Debugging Information
• Stack Traceback

Platform-Specific Information for the Run-Time Libraries

• Summary of Run-Time Configurations
• Specifying a Run-Time Library
• Choosing the Scheduling Policy
• Solaris-Specific Considerations
• Linux-Specific Considerations
• AIX-Specific Considerations
• Irix-Specific Considerations
• RTX-Specific Considerations
• HP-UX-Specific Considerations

Example of Binder Output File

Elaboration Order Handling in GNAT

• Elaboration Code
• Checking the Elaboration Order
• Controlling the Elaboration Order
• Controlling Elaboration in GNAT - Internal Calls
• Controlling Elaboration in GNAT - External Calls
• Default Behavior in GNAT - Ensuring Safety
• Treatment of Pragma Elaborate
• Elaboration Issues for Library Tasks
• Mixing Elaboration Models
• What to Do If the Default Elaboration Behavior Fails
• Elaboration for Access-to-Subprogram Values
• Summary of Procedures for Elaboration Control
• Other Elaboration Order Considerations

Conditional Compilation

• Use of Boolean Constants
• Debugging - A Special Case
• Conditionalizing Declarations
• Use of Alternative Implementations
• Preprocessing

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

Compatibility and Porting Guide

• Compatibility with Ada 83
• Compatibility between Ada 95 and Ada 2005
• Implementation-dependent characteristics
• Compatibility with HP Ada 83
• Compatibility with Other Ada Systems
• Representation Clauses

Microsoft Windows Topics

• Using GNAT on Windows
• CONSOLE and WINDOWS subsystems
• Temporary Files
• Mixed-Language Programming on Windows
• Windows Calling Conventions
• Introduction to Dynamic Link Libraries (DLLs)
• Using DLLs with GNAT
• Building DLLs with GNAT
• GNAT and Windows Resources
• Debugging a DLL
• Setting Stack Size from gnatlink
• Setting Heap Size from gnatlink
• Index