GNAT Pro User's Guide

GNAT Pro User's Guide

The GNAT Pro Ada Compiler
GNAT Pro Version 6.3.0w
Document revision level 150311
Date: 2009/06/27

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. The Cross-Referencing Tools gnatxref and gnatfind
13. The GNAT Pretty-Printer gnatpp
14. The GNAT Metric Tool gnatmetric
15. File Name Krunching Using gnatkr
16. Preprocessing Using gnatprep
17. The GNAT Library Browser gnatls
18. Cleaning Up Using gnatclean
19. GNAT and Libraries
20. Using the GNU make Utility
21. Memory Management Issues
22. Stack Related Facilities
23. Verifying Properties Using gnatcheck
24. Creating Sample Bodies Using gnatstub
25. Generating Ada Bindings for C and C++ headers
26. Other Utility Programs
28. Running and Debugging Ada Programs
27. 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 Correcting the List of Eliminate Pragmas
7.3.4 Making Your Executables Smaller
7.3.5 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

GNAT Project Manager

11.1 Introduction
11.2 Examples of Project Files
11.3 Project File Syntax
11.4 Objects and Sources in Project Files
11.5 Importing Projects
11.6 Project Extension
11.7 Project Hierarchy Extension
11.8 External References in Project Files
11.9 Packages in Project Files
11.10 Variables from Imported Projects
11.11 Naming Schemes
11.12 Library Projects
11.13 Stand-alone Library Projects
11.14 Switches Related to Project Files
11.15 Tools Supporting Project Files
11.16 An Extended Example
11.17 Project File Complete Syntax

The Cross-Referencing Tools gnatxref and gnatfind

12.1 gnatxref Switches
12.2 gnatfind Switches
12.3 Project Files for gnatxref and gnatfind
12.4 Regular Expressions in gnatfind and gnatxref
12.5 Examples of gnatxref Usage
12.6 Examples of gnatfind Usage

The GNAT Pretty-Printer gnatpp

13.1 Switches for gnatpp
13.2 Formatting Rules

The GNAT Metrics Tool gnatmetric

14.1 Switches for gnatmetric

File Name Krunching Using gnatkr

15.1 About gnatkr
15.2 Using gnatkr
15.3 Krunching Method
15.4 Examples of gnatkr Usage

Preprocessing Using gnatprep

16.1 Preprocessing Symbols
16.2 Using gnatprep
16.3 Switches for gnatprep
16.4 Form of Definitions File
16.5 Form of Input Text for gnatprep

The GNAT Library Browser gnatls

17.1 Running gnatls
17.2 Switches for gnatls
17.3 Example of gnatls Usage

Cleaning Up Using gnatclean

18.1 Running gnatclean
18.2 Switches for gnatclean

GNAT and Libraries

19.1 Introduction to Libraries in GNAT
19.2 General Ada Libraries
19.3 Stand-alone Ada Libraries
19.4 Rebuilding the GNAT Run-Time Library

Using the GNU make Utility

20.1 Using gnatmake in a Makefile
20.2 Automatically Creating a List of Directories
20.3 Generating the Command Line Switches
20.4 Overcoming Command Line Length Limits

Memory Management Issues

21.1 Some Useful Memory Pools
21.2 The GNAT Debug Pool Facility
21.3 The gnatmem Tool

Stack Related Facilities

22.1 Stack Overflow Checking
22.2 Static Stack Usage Analysis
22.3 Dynamic Stack Usage Analysis

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

21.3.1 Running gnatmem
21.3.2 Switches for gnatmem
21.3.3 Example of gnatmem Usage

Verifying Properties Using gnatcheck

23.1 Format of the Report File
23.2 General gnatcheck Switches
23.3 gnatcheck Rule Options
23.4 Adding the Results of Compiler Checks to gnatcheck Output
23.5 Project-Wide Checks
23.6 Predefined Rules

Sample Bodies Using gnatstub

24.1 Running gnatstub
24.2 Switches for gnatstub

Other Utility Programs

26.1 Using Other Utility Programs with GNAT
26.2 The External Symbol Naming Scheme of GNAT
26.3 Converting Ada Files to HTML with gnathtml

Code Coverage and Profiling

27.1 Code Coverage of Ada Programs using gcov
27.2 Profiling an Ada Program using gprof

Running and Debugging Ada Programs

28.1 The GNAT Debugger GDB
28.2 Running GDB
28.3 Introduction to GDB Commands
28.4 Using Ada Expressions
28.5 Calling User-Defined Subprograms
28.6 Using the Next Command in a Function
28.7 Breaking on Ada Exceptions
28.8 Ada Tasks
28.9 Debugging Generic Units
28.10 GNAT Abnormal Termination or Failure to Terminate
28.11 Naming Conventions for GNAT Source Files
28.12 Getting Internal Debugging Information
28.13 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

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