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

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 and 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 Interfacing with C++ constructors
2.11.5 Interfacing with C++ at the Class Level

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 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
3.2.18 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 Dynamic Allocation Control
4.2.6 Binding with Non-Ada Main Programs
4.2.7 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

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 Vectorization of loops
7.1.7 Other Optimization Switches
7.1.8 Optimization and Strict Aliasing

7.2 Text_IO Suggestions
7.3 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

7.4 Reducing Size of Executables with Unused Subprogram/Data Elimination

7.4.1 About unused subprogram/data elimination
7.4.2 Compilation options
7.4.3 Example of unused subprogram/data elimination

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.2 Building With Projects

11.2.1 Source Files and Directories
11.2.2 Object and Exec Directory
11.2.3 Main Subprograms
11.2.4 Tools Options in Project Files
11.2.5 Compiling with Project Files
11.2.6 Executable File Names
11.2.7 Avoid Duplication With Variables
11.2.8 Naming Schemes

11.3 Organizing Projects into Subsystems

11.3.1 Project Dependencies
11.3.2 Cyclic Project Dependencies
11.3.3 Sharing Between Projects
11.3.4 Global Attributes

11.4 Scenarios in Projects
11.5 Library Projects

11.5.1 Building Libraries
11.5.2 Using Library Projects
11.5.3 Stand-alone Library Projects
11.5.4 Installing a library with project files

11.6 Project Extension

11.6.1 Project Hierarchy Extension

11.7 Aggregate Projects

11.7.1 Building all main programs from a single project tree
11.7.2 Building a set of projects with a single command
11.7.3 Define a build environment
11.7.4 Performance improvements in builder
11.7.5 Syntax of aggregate projects
11.7.6 package Builder in aggregate projects

11.8 Aggregate Library Projects

11.8.1 Building aggregate library projects
11.8.2 Syntax of aggregate library projects

11.9 Project File Reference

11.9.1 Project Declaration
11.9.2 Qualified Projects
11.9.3 Declarations
11.9.4 Packages
11.9.5 Expressions
11.9.6 External Values
11.9.7 Typed String Declaration
11.9.8 Variables
11.9.9 Attributes
11.9.10 Case Statements

12. Tools Supporting Project Files

12.1 gnatmake and Project Files

12.1.1 Switches Related to Project Files
12.1.2 Switches and Project Files
12.1.3 Specifying Configuration Pragmas
12.1.4 Project Files and Main Subprograms
12.1.5 Library Project Files

12.2 The GNAT Driver and Project Files
12.3 The Development Environments

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

13.6 Examples of gnatfind Usage

14. The GNAT Pretty-Printer gnatpp

14.1 Switches for gnatpp

14.1.1 Alignment Control
14.1.2 Casing Control
14.1.3 Construct Layout Control
14.1.4 General Text Layout Control
14.1.5 Other Formatting Options
14.1.6 Setting the Source Search Path
14.1.7 Output File Control
14.1.8 Other gnatpp Switches

14.2 Formatting Rules

14.2.1 White Space and Empty Lines
14.2.2 Formatting Comments
14.2.3 Construct Layout
14.2.4 Name Casing

15. The GNAT Metric Tool gnatmetric

15.1 Switches for gnatmetric

15.1.1 Output File Control
15.1.2 Disable Metrics For Local Units
15.1.3 Specifying a set of metrics to compute

15.1.3.1 Line Metrics Control
15.1.3.2 Syntax Metrics Control
15.1.3.3 Complexity Metrics Control
15.1.3.4 Coupling Metrics Control

15.1.4 Other gnatmetric Switches
15.1.5 Generate project-wide metrics

16. File Name Krunching Using gnatkr

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

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

18. The GNAT Library Browser gnatls

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

19. Cleaning Up Using gnatclean

19.1 Running gnatclean
19.2 Switches for gnatclean

20. GNAT and Libraries

20.1 Introduction to Libraries in GNAT
20.2 General Ada Libraries

20.2.1 Building a library
20.2.2 Installing a library
20.2.3 Using a library

20.3 Stand-alone Ada Libraries

20.3.1 Introduction to Stand-alone Libraries
20.3.2 Building a Stand-alone Library
20.3.3 Creating a Stand-alone Library to be used in a non-Ada context
20.3.4 Restrictions in Stand-alone Libraries

20.4 Rebuilding the GNAT Run-Time Library

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

22. Memory Management Issues

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

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

23. Stack Related Facilities

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

24. Verifying Properties Using gnatcheck
25. Creating Sample Bodies Using gnatstub

25.1 Running gnatstub
25.2 Switches for gnatstub

26. 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 Current Limitations

27. Generating Ada Bindings for C and C++ headers

27.1 Running the binding generator
27.2 Generating bindings for C++ headers
27.3 Switches

28. Other Utility Programs

28.1 Using Other Utility Programs with GNAT
28.2 The External Symbol Naming Scheme of GNAT
28.3 Converting Ada Files to HTML with gnathtml
28.4 Installing gnathtml

29. Code Coverage and Profiling

29.1 Code Coverage of Ada Programs using gcov

29.1.1 Quick startup guide
29.1.2 Gnat specifics

29.2 Profiling an Ada Program using gprof

29.2.1 Compilation for profiling
29.2.2 Program execution
29.2.3 Running gprof
29.2.4 Interpretation of profiling results

30. Running and Debugging Ada Programs

30.1 The GNAT Debugger GDB
30.2 Running GDB
30.3 Introduction to GDB Commands
30.4 Using Ada Expressions
30.5 Calling User-Defined Subprograms
30.6 Using the Next Command in a Function
30.7 Stopping when Ada Exceptions are Raised
30.8 Ada Tasks
30.9 Debugging Generic Units
30.10 Remote Debugging using gdbserver
30.11 GNAT Abnormal Termination or Failure to Terminate
30.12 Naming Conventions for GNAT Source Files
30.13 Getting Internal Debugging Information
30.14 Stack Traceback

30.14.1 Non-Symbolic Traceback

30.14.1.1 Tracebacks From an Unhandled Exception
30.14.1.2 Tracebacks From Exception Occurrences
30.14.1.3 Tracebacks From Anywhere in a Program

30.14.2 Symbolic Traceback

30.14.2.1 Tracebacks From Exception Occurrences
30.14.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.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

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

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

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

E.6.1 The Clobber Parameter
E.6.2 The Volatile Parameter

F. Compatibility and Porting Guide

F.1 Compatibility with Ada 83

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

F.2 Compatibility between Ada 95 and Ada 2005
F.3 Implementation-dependent characteristics

F.3.1 Implementation-defined pragmas
F.3.2 Implementation-defined attributes
F.3.3 Libraries
F.3.4 Elaboration order
F.3.5 Target-specific aspects

F.4 Compatibility with Other Ada Systems
F.5 Representation Clauses
F.6 Compatibility with HP Ada 83

G. Microsoft Windows Topics

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

G.6.1 C Calling Convention
G.6.2 Stdcall Calling Convention
G.6.3 Win32 Calling Convention
G.6.4 DLL Calling Convention

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

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

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

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

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

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

G.12 GNAT and Windows Resources

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

G.13 Debugging a DLL

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

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

G.14 Setting Stack Size from gnatlink
G.15 Setting Heap Size from gnatlink

H. GNU Free Documentation License
Index