GNAT GPL User's Guide

GNAT GPL User's Guide

The GNAT Ada Compiler
GNAT GPL Edition, Version 2012
Document revision level 247945
Date: 2012/05/02

AdaCore
Copyright (C) 1995-2012, 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 GPL 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. Creating Unit Tests Using gnattest
27. Performing Dimensionality Analysis in GNAT
28. Generating Ada Bindings for C and C++ headers
29. Other Utility Programs
31. Running and Debugging Ada Programs
30. 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.6 Binding with Non-Ada Main Programs
4.2.7 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 Vectorization of loops
7.1.7 Other Optimization Switches
7.1.8 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 Sample Bodies Using gnatstub

25.1 Running gnatstub
25.2 Switches for gnatstub

Creating Unit Tests Using gnattest

26.1 Running gnattest
26.2 Switches for gnattest
26.3 Project Attributes for gnattest
26.4 Simple Example
26.5 Setting Up and Tearing Down the Testing Environment
26.6 Regenerating Tests
26.7 Default Test Behavior
26.8 Testing Primitive Operations of Tagged Types
26.9 Testing Inheritance
26.10 Tagged Types Substitutability Testing
26.11 Testing with Contracts
26.12 Additional Tests
26.13 Support for other platforms/run-times
26.14 Current Limitations

Other Utility Programs

29.1 Using Other Utility Programs with GNAT
29.2 The External Symbol Naming Scheme of GNAT
29.3 Converting Ada Files to HTML with gnathtml

Code Coverage and Profiling

30.1 Code Coverage of Ada Programs using gcov
30.2 Profiling an Ada Program using gprof

Running and Debugging Ada Programs

31.1 The GNAT Debugger GDB
31.2 Running GDB
31.3 Introduction to GDB Commands
31.4 Using Ada Expressions
31.5 Calling User-Defined Subprograms
31.6 Using the Next Command in a Function
31.7 Stopping when Ada Exceptions are Raised
31.8 Ada Tasks
31.9 Debugging Generic Units
31.10 Remote Debugging using gdbserver
31.11 GNAT Abnormal Termination or Failure to Terminate
31.12 Naming Conventions for GNAT Source Files
31.13 Getting Internal Debugging Information
31.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 RTX-Specific Considerations
A.8 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 Dispatching Calls
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.10 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