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++ 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 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

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 Other Optimization Switches
7.1.7 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 Correcting the List of Eliminate Pragmas
7.3.4 Making Your Executables Smaller
7.3.5 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.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.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 Specifying a set of metrics to compute

14.1.3.1 Line Metrics Control
14.1.3.2 Syntax Metrics Control
14.1.3.3 Complexity Metrics Control
14.1.3.4 Object-Oriented Metrics Control

14.1.4 Other gnatmetric Switches
14.1.5 Generate project-wide metrics

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

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

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. Stack Related Facilities

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

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

23.6.1 Abstract_Type_Declarations
23.6.2 Anonymous_Arrays
23.6.3 Anonymous_Subtypes
23.6.4 Blocks
23.6.5 Boolean_Relational_Operators
23.6.6 Controlled_Type_Declarations
23.6.7 Declarations_In_Blocks
23.6.8 Default_Parameters
23.6.9 Discriminated_Records
23.6.10 Enumeration_Ranges_In_CASE_Statements
23.6.11 Exceptions_As_Control_Flow
23.6.12 EXIT_Statements_With_No_Loop_Name
23.6.13 Expanded_Loop_Exit_Names
23.6.14 Explicit_Full_Discrete_Ranges
23.6.15 Float_Equality_Checks
23.6.16 Forbidden_Pragmas
23.6.17 Function_Style_Procedures
23.6.18 Generics_In_Subprograms
23.6.19 GOTO_Statements
23.6.20 Implicit_IN_Mode_Parameters
23.6.21 Implicit_SMALL_For_Fixed_Point_Types
23.6.22 Improperly_Located_Instantiations
23.6.23 Improper_Returns
23.6.24 Library_Level_Subprograms
23.6.25 Local_Packages
23.6.26 Metrics_Violation
23.6.27 Misnamed_Identifiers
23.6.28 Multiple_Entries_In_Protected_Definitions
23.6.29 Name_Clashes
23.6.30 Non_Qualified_Aggregates
23.6.31 Non_Short_Circuit_Operators
23.6.32 Non_SPARK_Attributes
23.6.33 Non_Tagged_Derived_Types
23.6.34 Non_Visible_Exceptions
23.6.35 Numeric_Literals
23.6.36 OTHERS_In_Aggregates
23.6.37 OTHERS_In_CASE_Statements
23.6.38 OTHERS_In_Exception_Handlers
23.6.39 Outer_Loop_Exits
23.6.40 Overloaded_Operators
23.6.41 Overly_Nested_Control_Structures
23.6.42 Parameters_Out_Of_Order
23.6.43 Positional_Actuals_For_Defaulted_Generic_Parameters
23.6.44 Positional_Actuals_For_Defaulted_Parameters
23.6.45 Positional_Components
23.6.46 Positional_Generic_Parameters
23.6.47 Positional_Parameters
23.6.48 Predefined_Numeric_Types
23.6.49 Raising_External_Exceptions
23.6.50 Raising_Predefined_Exceptions
23.6.51 Slices
23.6.52 Unassigned_OUT_Parameters
23.6.53 Uncommented_BEGIN_In_Package_Bodies
23.6.54 Unconstrained_Array_Returns
23.6.55 Universal_Ranges
23.6.56 Unnamed_Blocks_And_Loops
23.6.57 USE_PACKAGE_Clauses
23.6.58 Volatile_Objects_Without_Address_Clauses

24. Creating Sample Bodies Using gnatstub

24.1 Running gnatstub
24.2 Switches for gnatstub

25. Other Utility Programs

25.1 Using Other Utility Programs with GNAT
25.2 The External Symbol Naming Scheme of GNAT
25.3 Converting Ada Files to HTML with gnathtml
25.4 Installing gnathtml

26. Code Coverage and Profiling

26.1 Code Coverage of Ada Programs using gcov

26.1.1 Quick startup guide
26.1.2 Gnat specifics

26.2 Profiling an Ada Program using gprof

26.2.1 Compilation for profiling
26.2.2 Program execution
26.2.3 Running gprof
26.2.4 Interpretation of profiling results

27. Running and Debugging Ada Programs

27.1 The GNAT Debugger GDB
27.2 Running GDB
27.3 Introduction to GDB Commands
27.4 Using Ada Expressions
27.5 Calling User-Defined Subprograms
27.6 Using the Next Command in a Function
27.7 Breaking on Ada Exceptions
27.8 Ada Tasks
27.9 Debugging Generic Units
27.10 GNAT Abnormal Termination or Failure to Terminate
27.11 Naming Conventions for GNAT Source Files
27.12 Getting Internal Debugging Information
27.13 Stack Traceback

27.13.1 Non-Symbolic Traceback

27.13.1.1 Tracebacks From an Unhandled Exception
27.13.1.2 Tracebacks From Exception Occurrences
27.13.1.3 Tracebacks From Anywhere in a Program

27.13.2 Symbolic Traceback

27.13.2.1 Tracebacks From Exception Occurrences
27.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.5 Linux-Specific Considerations
A.6 AIX-Specific Considerations
A.7 Irix-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
G.10 Building DLLs with GNAT Project files
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