Table of Contents

About This Guide

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

1. 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.5.1 Building a New Program with GPS
1.5.2 Simple Debugging with GPS

1.6 Introduction to Glide and GVD

1.6.1 Building a New Program with Glide
1.6.2 Simple Debugging with GVD
1.6.3 Other Glide Features

2. The GNAT Compilation Model

2.1 Source Representation
2.2 Foreign Language Representation

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

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.10.1 Interfacing to C
2.10.2 Calling Conventions

2.11 Building Mixed Ada & C++ Programs

2.11.1 Interfacing to C++
2.11.2 Linking a Mixed C++ & Ada Program
2.11.3 A Simple Example
2.11.4 Adapting the Run Time to a New C++ Compiler

2.12 Comparison between GNAT and C/C++ Compilation Models
2.13 Comparison between GNAT and Conventional Ada Library Models

3. Compiling Using gcc

3.1 Compiling Programs
3.2 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
3.2.19 Code Generation Control

3.3 Search Paths and the Run-Time Library (RTL)
3.4 Order of Compilation Issues
3.5 Examples

4. Binding Using gnatbind

4.1 Running gnatbind
4.2 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

4.3 Command-Line Access
4.4 Search Paths for gnatbind
4.5 Examples of gnatbind Usage

5. 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

6. 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

7. Improving Performance

7.1 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

7.2 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

8. 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

9. Configuration Pragmas

9.1 Handling of Configuration Pragmas
9.2 The Configuration Pragmas Files

10. 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

11. GNAT Project Manager

11.1 Introduction

11.1.1 Project Files

11.2 Examples of Project Files

11.2.1 Common Sources with Different Switches and Directories

Source Files
Specifying the Object Directory
Specifying the Exec Directory
Project File Packages
Specifying Switch Settings
Main Subprograms
Executable File Names
Source File Naming Conventions
Source Language(s)

11.2.2 Using External Variables
11.2.3 Importing Other Projects
11.2.4 Extending a Project

11.3 Project File Syntax

11.3.1 Basic Syntax
11.3.2 Packages
11.3.3 Expressions
11.3.4 String Types
11.3.5 Variables
11.3.6 Attributes
11.3.7 Associative Array Attributes
11.3.8 case Constructions

11.4 Objects and Sources in Project Files

11.4.1 Object Directory
11.4.2 Exec Directory
11.4.3 Source Directories
11.4.4 Source File Names

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.15.1 gnatmake and Project Files

11.15.1.1 Switches and Project Files
11.15.1.2 Specifying Configuration Pragmas
11.15.1.3 Project Files and Main Subprograms
11.15.1.4 Library Project Files

11.15.2 The GNAT Driver and Project Files
11.15.3 Glide and Project Files

11.16 An Extended Example
11.17 Project File Complete Syntax

12. 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.5.1 General Usage
12.5.2 Using gnatxref with vi

12.6 Examples of gnatfind Usage

13. The GNAT Pretty-Printer gnatpp

13.1 Switches for gnatpp

13.1.1 Alignment Control
13.1.2 Casing Control
13.1.3 Construct Layout Control
13.1.4 General Text Layout Control
13.1.5 Other Formatting Options
13.1.6 Setting the Source Search Path
13.1.7 Output File Control
13.1.8 Other gnatpp Switches

13.2 Formatting Rules

13.2.1 White Space and Empty Lines
13.2.2 Formatting Comments
13.2.3 Construct Layout
13.2.4 Name Casing

14. The GNAT Metric Tool gnatmetric

14.1 Switches for gnatmetric

14.1.1 Output File Control
14.1.2 Disable Metrics For Local Units
14.1.3 Line Metrics Control
14.1.4 Syntax Metrics Control
14.1.5 Complexity Metrics Control
14.1.6 Other gnatmetric Switches

15. File Name Krunching Using gnatkr

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

16. 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

17. The GNAT Library Browser gnatls

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

18. Cleaning Up Using gnatclean

18.1 Running gnatclean
18.2 Switches for gnatclean
18.3 Examples of gnatclean Usage

19. GNAT and Libraries

19.1 Introduction to Libraries in GNAT
19.2 General Ada Libraries

19.2.1 Building a library
19.2.2 Installing a library
19.2.3 Using a library

19.3 Stand-alone Ada Libraries

19.3.1 Introduction to Stand-alone Libraries
19.3.2 Building a Stand-alone Library
19.3.3 Creating a Stand-alone Library to be used in a non-Ada context
19.3.4 Restrictions in Stand-alone Libraries

19.4 Rebuilding the GNAT Run-Time Library

20. 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

21. Memory Management Issues

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

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

22. Creating Sample Bodies Using gnatstub

22.1 Running gnatstub
22.2 Switches for gnatstub

23. 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
23.5 Installing gnathtml

24. 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

24.13.1 Non-Symbolic Traceback

24.13.1.1 Tracebacks From an Unhandled Exception
24.13.1.2 Tracebacks From Exception Occurrences
24.13.1.3 Tracebacks From Anywhere in a Program

24.13.2 Symbolic Traceback

24.13.2.1 Tracebacks From Exception Occurrences
24.13.2.2 Tracebacks From Anywhere in a Program

A. 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.4.1 Solaris Threads Issues
A.4.2 Building and Debugging 64-bit Applications

A.5 IRIX-Specific Considerations
A.6 Linux-Specific Considerations
A.7 AIX-Specific Considerations

B. Example of Binder Output File
C. 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

D. 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

D.6.1 The Clobber Parameter
D.6.2 The Volatile Parameter

E. Compatibility and Porting Guide

E.1 Compatibility with Ada 83

E.1.1 Legal Ada 83 programs that are illegal in Ada 95
E.1.2 More deterministic semantics
E.1.3 Changed semantics
E.1.4 Other language compatibility issues

E.2 Implementation-dependent characteristics

E.2.1 Implementation-defined pragmas
E.2.2 Implementation-defined attributes
E.2.3 Libraries
E.2.4 Elaboration order
E.2.5 Target-specific aspects

E.3 Compatibility with Other Ada 95 Systems
E.4 Representation Clauses
E.5 Compatibility with DEC Ada 83

F. Microsoft Windows Topics

F.1 Using GNAT on Windows
F.2 Using a network installation of GNAT
F.3 CONSOLE and WINDOWS subsystems
F.4 Temporary Files
F.5 Mixed-Language Programming on Windows
F.6 Windows Calling Conventions

F.6.1 C Calling Convention
F.6.2 Stdcall Calling Convention
F.6.3 DLL Calling Convention

F.7 Introduction to Dynamic Link Libraries (DLLs)
F.8 Using DLLs with GNAT

F.8.1 Creating an Ada Spec for the DLL Services
F.8.2 Creating an Import Library

F.8.2.1 The Definition File
F.8.2.2 GNAT-Style Import Library
F.8.2.3 Microsoft-Style Import Library

F.9 Building DLLs with GNAT
F.10 Building DLLs with GNAT Project files
F.11 Building DLLs with gnatdll

F.11.1 Limitations When Using Ada DLLs from Ada
F.11.2 Exporting Ada Entities
F.11.3 Ada DLLs and Elaboration
F.11.4 Ada DLLs and Finalization
F.11.5 Creating a Spec for Ada DLLs
F.11.6 Creating the Definition File
F.11.7 Using gnatdll

F.11.7.1 gnatdll Example
F.11.7.2 gnatdll behind the Scenes
F.11.7.3 Using dlltool

F.12 GNAT and Windows Resources

F.12.1 Building Resources
F.12.2 Compiling Resources
F.12.3 Using Resources

F.13 Debugging a DLL

F.13.1 Program and DLL Both Built with GCC/GNAT
F.13.2 Program Built with Foreign Tools and DLL Built with GCC/GNAT

F.13.2.1 Debugging the DLL Directly
F.13.2.2 Attaching to a Running Process

F.14 GNAT and COM/DCOM Objects

G. GNU Free Documentation License
Index