GNAT User's Guide

GNAT User's Guide

The GNAT Ada 95 Compiler
GNAT Academic Edition, Version 2005
Document revision level 1.265
Date: 2005/05/19 14:36:38

AdaCore
Copyright (C) 1995-2005, 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 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. Creating Sample Bodies Using gnatstub
23. Other Utility Programs
24. Running and Debugging Ada Programs
A. Platform-Specific Information for the Run-Time Libraries
B. Example of Binder Output File
C. Elaboration Order Handling in GNAT
D. Inline Assembler
E. Compatibility and Porting Guide
F. Microsoft Windows Topics
G. 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
1.6 Introduction to Glide and GVD

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 & 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 Stack Overflow Checking
3.2.8 Using gcc for Syntax Checking
3.2.9 Using gcc for Semantic Checking
3.2.10 Compiling Different Versions of Ada
3.2.11 Character Set Control
3.2.12 File Naming Control
3.2.13 Subprogram Inlining Control
3.2.14 Auxiliary Output Control
3.2.15 Debugging Control
3.2.16 Exception Handling Control
3.2.17 Units to Sources Mapping Files
3.2.18 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
5.3 Setting Stack Size from gnatlink
5.4 Setting Heap Size from 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 Reducing the Size of Ada Executables with gnatelim

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 Optimization and Strict Aliasing

Reducing the Size of Ada Executables with gnatelim

7.2.1 About gnatelim
7.2.2 Running gnatelim
7.2.3 Correcting the List of Eliminate Pragmas
7.2.4 Making Your Executables Smaller
7.2.5 Summary of the gnatelim Usage Cycle

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 Using gnatprep
16.2 Switches for gnatprep
16.3 Form of Definitions File
16.4 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
18.3 Examples of gnatclean Usage

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

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

 Sample Bodies Using gnatstub

22.1 Running gnatstub
22.2 Switches for gnatstub

Other Utility Programs

23.1 Using Other Utility Programs with GNAT
23.2 The External Symbol Naming Scheme of GNAT
23.3 Ada Mode for Glide
23.4 Converting Ada Files to HTML with gnathtml

Running and Debugging Ada Programs

24.1 The GNAT Debugger GDB
24.2 Running GDB
24.3 Introduction to GDB Commands
24.4 Using Ada Expressions
24.5 Calling User-Defined Subprograms
24.6 Using the Next Command in a Function
24.7 Breaking on Ada Exceptions
24.8 Ada Tasks
24.9 Debugging Generic Units
24.10 GNAT Abnormal Termination or Failure to Terminate
24.11 Naming Conventions for GNAT Source Files
24.12 Getting Internal Debugging Information
24.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 IRIX-Specific Considerations
A.6 Linux-Specific Considerations
A.7 AIX-Specific Considerations

Example of Binder Output File Elaboration Order Handling in GNAT

C.1 Elaboration Code in Ada 95
C.2 Checking the Elaboration Order in Ada 95
C.3 Controlling the Elaboration Order in Ada 95
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

Inline Assembler

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

Compatibility and Porting Guide

E.1 Compatibility with Ada 83
E.2 Implementation-dependent characteristics
E.5 Compatibility with DEC Ada 83
E.3 Compatibility with Other Ada 95 Systems
E.4 Representation Clauses

Microsoft Windows Topics

F.1 Using GNAT on Windows
F.3 CONSOLE and WINDOWS subsystems
F.4 Temporary Files
F.5 Mixed-Language Programming on Windows
F.6 Windows Calling Conventions
F.7 Introduction to Dynamic Link Libraries (DLLs)
F.8 Using DLLs with GNAT
F.9 Building DLLs with GNAT
F.12 GNAT and Windows Resources
F.13 Debugging a DLL
F.14 GNAT and COM/DCOM Objects

Index