GNAT Pro User's Guide

GNAT Pro User's Guide

The GNAT Pro Ada Compiler
GNAT Pro Version 6.4.0w
Document revision level 161133
Date: 2010/03/08

AdaCore
Copyright (C) 1995-2008, Free Software Foundation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU Free Documentation License", with the Front-Cover Texts being "GNAT Pro User's Guide", and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

About This Guide
1. Getting Started with GNAT
2. The GNAT Compilation Model
3. Compiling Using gcc
4. Binding Using gnatbind
5. Linking Using gnatlink
6. The GNAT Make Program gnatmake
7. Improving Performance
8. Renaming Files Using gnatchop
9. Configuration Pragmas
10. Handling Arbitrary File Naming Conventions Using gnatname
11. GNAT Project Manager
12. Tools Supporting Project Files
13. The Cross-Referencing Tools gnatxref and gnatfind
14. The GNAT Pretty-Printer gnatpp
15. The GNAT Metric Tool gnatmetric
16. File Name Krunching Using gnatkr
17. Preprocessing Using gnatprep
18. The GNAT Library Browser gnatls
19. Cleaning Up Using gnatclean
20. GNAT and Libraries
21. Using the GNU make Utility
22. Memory Management Issues
23. Stack Related Facilities
24. Verifying Properties Using gnatcheck
25. Creating Sample Bodies Using gnatstub
26. Generating Ada Bindings for C and C++ headers
27. Other Utility Programs
29. Running and Debugging Ada Programs
28. Code Coverage and Profiling
A. Platform-Specific Information for the Run-Time Libraries
B. Example of Binder Output File
C. Elaboration Order Handling in GNAT
D. Conditional Compilation
E. Inline Assembler
F. Compatibility and Porting Guide
G. Microsoft Windows Topics
H. 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

1.1 Running GNAT
1.2 Running a Simple Ada Program
1.3 Running a Program with Multiple Units
1.4 Using the gnatmake Utility
1.5 Introduction to GPS

The GNAT Compilation Model

2.1 Source Representation
2.2 Foreign Language Representation
2.3 File Naming Rules
2.4 Using Other File Names
2.5 Alternative File Naming Schemes
2.6 Generating Object Files
2.7 Source Dependencies
2.8 The Ada Library Information Files
2.9 Binding an Ada Program
2.10 Mixed Language Programming
2.11 Building Mixed Ada and C++ Programs
2.12 Comparison between GNAT and C/C++ Compilation Models
2.13 Comparison between GNAT and Conventional Ada Library Models

Foreign Language Representation

2.2.1 Latin-1
2.2.2 Other 8-Bit Codes
2.2.3 Wide Character Encodings

Compiling Ada Programs With gcc

3.1 Compiling Programs
3.2 Switches for gcc
3.3 Search Paths and the Run-Time Library (RTL)
3.4 Order of Compilation Issues
3.5 Examples

Switches for gcc

3.2.1 Output and Error Message Control
3.2.2 Warning Message Control
3.2.3 Debugging and Assertion Control
3.2.4 Validity Checking
3.2.5 Style Checking
3.2.6 Run-Time Checks
3.2.7 Using gcc for Syntax Checking
3.2.8 Using gcc for Semantic Checking
3.2.9 Compiling Different Versions of Ada
3.2.10 Character Set Control
3.2.11 File Naming Control
3.2.12 Subprogram Inlining Control
3.2.13 Auxiliary Output Control
3.2.14 Debugging Control
3.2.15 Exception Handling Control
3.2.16 Units to Sources Mapping Files
3.2.17 Integrated Preprocessing

Binding Ada Programs With gnatbind

4.1 Running gnatbind
4.2 Switches for gnatbind
4.3 Command-Line Access
4.4 Search Paths for gnatbind
4.5 Examples of gnatbind Usage

Switches for gnatbind

4.2.1 Consistency-Checking Modes
4.2.2 Binder Error Message Control
4.2.3 Elaboration Control
4.2.4 Output Control
4.2.5 Binding with Non-Ada Main Programs
4.2.6 Binding Programs with No Main Subprogram

Linking Using gnatlink

5.1 Running gnatlink
5.2 Switches for gnatlink

The GNAT Make Program gnatmake

6.1 Running gnatmake
6.2 Switches for gnatmake
6.3 Mode Switches for gnatmake
6.4 Notes on the Command Line
6.5 How gnatmake Works
6.6 Examples of gnatmake Usage

Improving Performance

7.1 Performance Considerations
7.2 Text_IO Suggestions
7.3 Reducing Size of Ada Executables with gnatelim
7.4 Reducing Size of Executables with Unused Subprogram/Data Elimination

Performance Considerations

7.1.1 Controlling Run-Time Checks
7.1.2 Use of Restrictions
7.1.3 Optimization Levels
7.1.4 Debugging Optimized Code
7.1.5 Inlining of Subprograms
7.1.6 Other Optimization Switches
7.1.7 Optimization and Strict Aliasing

Reducing Size of Ada Executables with gnatelim

7.3.1 About gnatelim
7.3.2 Running gnatelim
7.3.3 Processing Precompiled Libraries
7.3.4 Correcting the List of Eliminate Pragmas
7.3.5 Making Your Executables Smaller
7.3.6 Summary of the gnatelim Usage Cycle

Reducing Size of Executables with unused subprogram/data elimination

7.4.1 About unused subprogram/data elimination
7.4.2 Compilation options

Renaming Files Using gnatchop

8.1 Handling Files with Multiple Units
8.2 Operating gnatchop in Compilation Mode
8.3 Command Line for gnatchop
8.4 Switches for gnatchop
8.5 Examples of gnatchop Usage

Configuration Pragmas

9.1 Handling of Configuration Pragmas
9.2 The Configuration Pragmas Files

Handling Arbitrary File Naming Conventions Using gnatname

10.1 Arbitrary File Naming Conventions
10.2 Running gnatname
10.3 Switches for gnatname
10.4 Examples of gnatname Usage

The Cross-Referencing Tools gnatxref and gnatfind

13.1 gnatxref Switches
13.2 gnatfind Switches
13.3 Project Files for gnatxref and gnatfind
13.4 Regular Expressions in gnatfind and gnatxref
13.5 Examples of gnatxref Usage
13.6 Examples of gnatfind Usage

The GNAT Pretty-Printer gnatpp

14.1 Switches for gnatpp
14.2 Formatting Rules

The GNAT Metrics Tool gnatmetric

15.1 Switches for gnatmetric

File Name Krunching Using gnatkr

16.1 About gnatkr
16.2 Using gnatkr
16.3 Krunching Method
16.4 Examples of gnatkr Usage

Preprocessing Using gnatprep

17.1 Preprocessing Symbols
17.2 Using gnatprep
17.3 Switches for gnatprep
17.4 Form of Definitions File
17.5 Form of Input Text for gnatprep

The GNAT Library Browser gnatls

18.1 Running gnatls
18.2 Switches for gnatls
18.3 Example of gnatls Usage

Cleaning Up Using gnatclean

19.1 Running gnatclean
19.2 Switches for gnatclean

GNAT and Libraries

20.1 Introduction to Libraries in GNAT
20.2 General Ada Libraries
20.3 Stand-alone Ada Libraries
20.4 Rebuilding the GNAT Run-Time Library

Using the GNU make Utility

21.1 Using gnatmake in a Makefile
21.2 Automatically Creating a List of Directories
21.3 Generating the Command Line Switches
21.4 Overcoming Command Line Length Limits

Memory Management Issues

22.1 Some Useful Memory Pools
22.2 The GNAT Debug Pool Facility
22.3 The gnatmem Tool

Stack Related Facilities

23.1 Stack Overflow Checking
23.2 Static Stack Usage Analysis
23.3 Dynamic Stack Usage Analysis

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

22.3.1 Running gnatmem
22.3.2 Switches for gnatmem
22.3.3 Example of gnatmem Usage

Verifying Properties Using gnatcheck

24.1 Format of the Report File
24.2 General gnatcheck Switches
24.3 gnatcheck Rule Options
24.4 Adding the Results of Compiler Checks to gnatcheck Output
24.5 Project-Wide Checks
24.6 Rule exemption
24.7 Predefined Rules
24.8 Example of gnatcheck Usage

Sample Bodies Using gnatstub

25.1 Running gnatstub
25.2 Switches for gnatstub

Other Utility Programs

27.1 Using Other Utility Programs with GNAT
27.2 The External Symbol Naming Scheme of GNAT
27.3 Converting Ada Files to HTML with gnathtml

Code Coverage and Profiling

28.1 Code Coverage of Ada Programs using gcov
28.2 Profiling an Ada Program using gprof

Running and Debugging Ada Programs

29.1 The GNAT Debugger GDB
29.2 Running GDB
29.3 Introduction to GDB Commands
29.4 Using Ada Expressions
29.5 Calling User-Defined Subprograms
29.6 Using the Next Command in a Function
29.7 Stopping when Ada Exceptions are Raised
29.8 Ada Tasks
29.9 Debugging Generic Units
29.10 Remote Debugging using gdbserver
29.11 GNAT Abnormal Termination or Failure to Terminate
29.12 Naming Conventions for GNAT Source Files
29.13 Getting Internal Debugging Information
29.14 Stack Traceback

Platform-Specific Information for the Run-Time Libraries

A.1 Summary of Run-Time Configurations
A.2 Specifying a Run-Time Library
A.3 Choosing the Scheduling Policy
A.4 Solaris-Specific Considerations
A.5 Linux-Specific Considerations
A.6 AIX-Specific Considerations
A.7 Irix-Specific Considerations
A.8 RTX-Specific Considerations
A.9 HP-UX-Specific Considerations

Example of Binder Output File Elaboration Order Handling in GNAT

C.1 Elaboration Code
C.2 Checking the Elaboration Order
C.3 Controlling the Elaboration Order
C.4 Controlling Elaboration in GNAT - Internal Calls
C.5 Controlling Elaboration in GNAT - External Calls
C.6 Default Behavior in GNAT - Ensuring Safety
C.7 Treatment of Pragma Elaborate
C.8 Elaboration Issues for Library Tasks
C.9 Mixing Elaboration Models
C.10 What to Do If the Default Elaboration Behavior Fails
C.11 Elaboration for Access-to-Subprogram Values
C.12 Summary of Procedures for Elaboration Control
C.13 Other Elaboration Order Considerations

Conditional Compilation

D.1 Use of Boolean Constants
D.2 Debugging - A Special Case
D.3 Conditionalizing Declarations
D.4 Use of Alternative Implementations
D.5 Preprocessing

Inline Assembler

E.1 Basic Assembler Syntax
E.2 A Simple Example of Inline Assembler
E.3 Output Variables in Inline Assembler
E.4 Input Variables in Inline Assembler
E.5 Inlining Inline Assembler Code
E.6 Other Asm Functionality

Compatibility and Porting Guide

F.1 Compatibility with Ada 83
F.2 Compatibility between Ada 95 and Ada 2005
F.3 Implementation-dependent characteristics
F.6 Compatibility with HP Ada 83
F.4 Compatibility with Other Ada Systems
F.5 Representation Clauses

Microsoft Windows Topics

G.1 Using GNAT on Windows
G.3 CONSOLE and WINDOWS subsystems
G.4 Temporary Files
G.5 Mixed-Language Programming on Windows
G.6 Windows Calling Conventions
G.7 Introduction to Dynamic Link Libraries (DLLs)
G.8 Using DLLs with GNAT
G.9 Building DLLs with GNAT
G.12 GNAT and Windows Resources
G.13 Debugging a DLL
G.14 Setting Stack Size from gnatlink
G.15 Setting Heap Size from gnatlink

Index