GNAT User's Guide for Native Platforms

GNAT User's Guide for Native Platforms

GNAT User's Guide for Native Platforms , November 18, 2015

AdaCore

Copyright © 2008-2016, Free Software Foundation

`GNAT, The GNU Ada Development Environment'

GCC version 6.3.0
AdaCore

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "GNAT User's Guide for Native Platforms", and with no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License.

• About This Guide
• Getting Started with GNAT
• The GNAT Compilation Model
• Building Executable Programs with GNAT
• GNAT Project Manager
• Tools Supporting Project Files
• GNAT Utility Programs
• GNAT and Program Execution
• Platform-Specific Information
• Example of Binder Output File
• Elaboration Order Handling in GNAT
• Inline Assembler
• 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
• A Note to Readers of Previous Versions of the Manual
• Conventions

Getting Started with GNAT

• Running GNAT
• Running a Simple Ada Program
• Running a Program with Multiple Units
• Using the gnatmake Utility

The GNAT Compilation Model

• Source Representation
• Foreign Language Representation
• File Naming Topics and Utilities
• Configuration Pragmas
• Generating Object Files
• Source Dependencies
• The Ada Library Information Files
• Binding an Ada Program
• GNAT and Libraries
• Conditional Compilation
• Mixed Language Programming
• GNAT and Other Compilation Models
• Using GNAT Files with External Tools

Foreign Language Representation

• Latin-1
• Other 8-Bit Codes
• Wide_Character Encodings
• Wide_Wide_Character Encodings

File Naming Topics and Utilities

• File Naming Rules
• Using Other File Names
• Alternative File Naming Schemes
• Handling Arbitrary File Naming Conventions with gnatname
• File Name Krunching with gnatkr
• Renaming Files with gnatchop

Handling Arbitrary File Naming Conventions with gnatname

• Arbitrary File Naming Conventions
• Running gnatname
• Switches for gnatname
• Examples of gnatname Usage

File Name Krunching with gnatkr

• About gnatkr
• Using gnatkr
• Krunching Method
• Examples of gnatkr Usage

Renaming Files with gnatchop

• Handling Files with Multiple Units
• Operating gnatchop in Compilation Mode
• Command Line for gnatchop
• Switches for gnatchop
• Examples of gnatchop Usage

Configuration Pragmas

• Handling of Configuration Pragmas
• The Configuration Pragmas Files

GNAT and Libraries

• Introduction to Libraries in GNAT
• General Ada Libraries
• Stand-alone Ada Libraries
• Rebuilding the GNAT Run-Time Library

General Ada Libraries

• Building a library
• Installing a library
• Using a library

Stand-alone Ada Libraries

• Introduction to Stand-alone Libraries
• Building a Stand-alone Library
• Creating a Stand-alone Library to be used in a non-Ada context
• Restrictions in Stand-alone Libraries

Conditional Compilation

• Modeling Conditional Compilation in Ada
• Preprocessing with gnatprep
• Integrated Preprocessing

Modeling Conditional Compilation in Ada

• Use of Boolean Constants
• Debugging - A Special Case
• Conditionalizing Declarations
• Use of Alternative Implementations
• Preprocessing

Preprocessing with gnatprep

• Preprocessing Symbols
• Using gnatprep
• Switches for gnatprep
• Form of Definitions File
• Form of Input Text for gnatprep

Mixed Language Programming

• Interfacing to C
• Calling Conventions
• Building Mixed Ada and C++ Programs
• Generating Ada Bindings for C and C++ headers
• Generating C Headers for Ada Specifications

Building Mixed Ada and C++ Programs

• Interfacing to C++
• Linking a Mixed C++ & Ada Program
• A Simple Example
• Interfacing with C++ constructors
• Interfacing with C++ at the Class Level

Generating Ada Bindings for C and C++ headers

• Running the Binding Generator
• Generating Bindings for C++ Headers
• Switches

Generating C Headers for Ada Specifications

• Running the C Header Generator

GNAT and Other Compilation Models

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

Using GNAT Files with External Tools

• Using Other Utility Programs with GNAT
• The External Symbol Naming Scheme of GNAT

Building Executable Programs with GNAT

• Building with gnatmake
• Compiling with gcc
• Compiler Switches
• Binding with gnatbind
• Linking with gnatlink
• Using the GNU make Utility

Building with gnatmake

• Running gnatmake
• Switches for gnatmake
• Mode Switches for gnatmake
• Notes on the Command Line
• How gnatmake Works
• Examples of gnatmake Usage

Compiling with gcc

• Compiling Programs
• Search Paths and the Run-Time Library (RTL)
• Order of Compilation Issues
• Examples

Compiler Switches

• Alphabetical List of All Switches
• Output and Error Message Control
• Warning Message Control
• Debugging and Assertion Control
• Validity Checking
• Style Checking
• Run-Time Checks
• Using gcc for Syntax Checking
• Using gcc for Semantic Checking
• Compiling Different Versions of Ada
• Character Set Control
• File Naming Control
• Subprogram Inlining Control
• Auxiliary Output Control
• Debugging Control
• Exception Handling Control
• Units to Sources Mapping Files
• Code Generation Control

Binding with gnatbind

• Running gnatbind
• Switches for gnatbind
• Command-Line Access
• Search Paths for gnatbind
• Examples of gnatbind Usage

Switches for gnatbind

• Consistency-Checking Modes
• Binder Error Message Control
• Elaboration Control
• Output Control
• Dynamic Allocation Control
• Binding with Non-Ada Main Programs
• Binding Programs with No Main Subprogram

Linking with gnatlink

• Running gnatlink
• Switches for gnatlink

Using the GNU make Utility

• Using gnatmake in a Makefile
• Automatically Creating a List of Directories
• Generating the Command Line Switches
• Overcoming Command Line Length Limits

GNAT Project Manager

• Introduction
• Building With Projects
• Organizing Projects into Subsystems
• Scenarios in Projects
• Library Projects
• Project Extension
• Aggregate Projects
• Aggregate Library Projects
• Project File Reference

Building With Projects

• Source Files and Directories
• Duplicate Sources in Projects
• Object and Exec Directory
• Main Subprograms
• Tools Options in Project Files
• Compiling with Project Files
• Executable File Names
• Avoid Duplication With Variables
• Naming Schemes
• Installation
• Distributed support

Organizing Projects into Subsystems

• Project Dependencies
• Cyclic Project Dependencies
• Sharing Between Projects
• Global Attributes

Library Projects

• Building Libraries
• Using Library Projects
• Stand-alone Library Projects
• Installing a library with project files

Project Extension

• Project Hierarchy Extension

Aggregate Projects

• Building all main programs from a single project tree
• Building a set of projects with a single command
• Define a build environment
• Performance improvements in builder
• Syntax of aggregate projects
• package Builder in aggregate projects

Aggregate Library Projects

• Building aggregate library projects
• Syntax of aggregate library projects

Project File Reference

• Project Declaration
• Qualified Projects
• Declarations
• Packages
• Expressions
• External Values
• Typed String Declaration
• Variables
• Case Constructions
• Attributes

Attributes

• Project Level Attributes
• Package Binder Attributes
• Package Builder Attributes
• Package Clean Attributes
• Package Compiler Attributes
• Package Cross_Reference Attributes
• Package Finder Attributes
• Package gnatls Attributes
• Package IDE Attributes
• Package Install Attributes
• Package Linker Attributes
• Package Naming Attributes
• Package Remote Attributes
• Package Stack Attributes
• Package Synchronize Attributes

Tools Supporting Project Files

• gnatmake and Project Files
• The GNAT Driver and Project Files

gnatmake and Project Files

• Switches Related to Project Files
• Switches and Project Files
• Specifying Configuration Pragmas
• Project Files and Main Subprograms
• Library Project Files

GNAT Utility Programs

• The File Cleanup Utility gnatclean
• The GNAT Library Browser gnatls
• The Cross-Referencing Tools gnatxref and gnatfind
• The Ada to HTML Converter gnathtml

The File Cleanup Utility gnatclean

• Running gnatclean
• Switches for gnatclean

The GNAT Library Browser gnatls

• Running gnatls
• Switches for gnatls
• Example of gnatls Usage

The Cross-Referencing Tools gnatxref and gnatfind

• gnatxref Switches
• gnatfind Switches
• Project Files for gnatxref and gnatfind
• Regular Expressions in gnatfind and gnatxref
• Examples of gnatxref Usage
• Examples of gnatfind Usage

Examples of gnatxref Usage

• General Usage
• Using gnatxref with vi

The Ada to HTML Converter gnathtml

• Invoking gnathtml
• Installing gnathtml

GNAT and Program Execution

• Running and Debugging Ada Programs
• Code Coverage and Profiling
• Improving Performance
• Overflow Check Handling in GNAT
• Performing Dimensionality Analysis in GNAT
• Stack Related Facilities
• Memory Management Issues

Running and Debugging Ada Programs

• The GNAT Debugger GDB
• Running GDB
• Introduction to GDB Commands
• Using Ada Expressions
• Calling User-Defined Subprograms
• Using the next Command in a Function
• Stopping When Ada Exceptions Are Raised
• Ada Tasks
• Debugging Generic Units
• Remote Debugging with gdbserver
• GNAT Abnormal Termination or Failure to Terminate
• Naming Conventions for GNAT Source Files
• Getting Internal Debugging Information
• Stack Traceback

Stack Traceback

• Non-Symbolic Traceback
• Symbolic Traceback

Code Coverage and Profiling

• Code Coverage of Ada Programs with gcov
• Profiling an Ada Program with gprof

Code Coverage of Ada Programs with gcov

• Quick startup guide
• GNAT specifics

Profiling an Ada Program with gprof

• Compilation for profiling
• Program execution
• Running gprof
• Interpretation of profiling results

Improving Performance

• Performance Considerations
• Text_IO Suggestions
• Reducing Size of Executables with Unused Subprogram/Data Elimination

Performance Considerations

• Controlling Run-Time Checks
• Use of Restrictions
• Optimization Levels
• Debugging Optimized Code
• Inlining of Subprograms
• Floating_Point_Operations
• Vectorization of loops
• Other Optimization Switches
• Optimization and Strict Aliasing
• Aliased Variables and Optimization
• Atomic Variables and Optimization
• Passive Task Optimization

Reducing Size of Executables with Unused Subprogram/Data Elimination

• About unused subprogram/data elimination
• Compilation options
• Example of unused subprogram/data elimination

Overflow Check Handling in GNAT

• Background
• Management of Overflows in GNAT
• Specifying the Desired Mode
• Default Settings
• Implementation Notes

Stack Related Facilities

• Stack Overflow Checking
• Static Stack Usage Analysis
• Dynamic Stack Usage Analysis

Memory Management Issues

• Some Useful Memory Pools
• The GNAT Debug Pool Facility

Platform-Specific Information

• Run-Time Libraries
• Specifying a Run-Time Library
• Microsoft Windows Topics
• Mac OS Topics

Run-Time Libraries

• Summary of Run-Time Configurations

Specifying a Run-Time Library

• Choosing the Scheduling Policy
• Solaris-Specific Considerations
• Solaris Threads Issues
• AIX-Specific Considerations

Microsoft Windows Topics

• Using GNAT on Windows
• Using a network installation of GNAT
• CONSOLE and WINDOWS subsystems
• Temporary Files
• Mixed-Language Programming on Windows
• Windows Specific Add-Ons

Mixed-Language Programming on Windows

• Windows Calling Conventions
• Introduction to Dynamic Link Libraries (DLLs)
• Using DLLs with GNAT
• Building DLLs with GNAT Project files
• Building DLLs with GNAT
• Building DLLs with gnatdll
• Ada DLLs and Finalization
• Creating a Spec for Ada DLLs
• GNAT and Windows Resources
• Using GNAT DLLs from Microsoft Visual Studio Applications
• Debugging a DLL
• Setting Stack Size from gnatlink
• Setting Heap Size from gnatlink

Windows Calling Conventions

• C Calling Convention
• Stdcall Calling Convention
• Win32 Calling Convention
• DLL Calling Convention

Using DLLs with GNAT

• Creating an Ada Spec for the DLL Services
• Creating an Import Library

Building DLLs with gnatdll

• Limitations When Using Ada DLLs from Ada
• Exporting Ada Entities
• Ada DLLs and Elaboration

Creating a Spec for Ada DLLs

• Creating the Definition File
• Using gnatdll

GNAT and Windows Resources

• Building Resources
• Compiling Resources
• Using Resources

Debugging a DLL

• Program and DLL Both Built with GCC/GNAT
• Program Built with Foreign Tools and DLL Built with GCC/GNAT

Windows Specific Add-Ons

• Win32Ada
• wPOSIX

Mac OS Topics

• Codesigning the Debugger

Elaboration Order Handling in GNAT

• Elaboration Code
• Checking the Elaboration Order
• Controlling the Elaboration Order
• Controlling Elaboration in GNAT - Internal Calls
• Controlling Elaboration in GNAT - External Calls
• Default Behavior in GNAT - Ensuring Safety
• Treatment of Pragma Elaborate
• Elaboration Issues for Library Tasks
• Mixing Elaboration Models
• What to Do If the Default Elaboration Behavior Fails
• Elaboration for Indirect Calls
• Summary of Procedures for Elaboration Control
• Other Elaboration Order Considerations
• Determining the Chosen Elaboration Order

Inline Assembler

• Basic Assembler Syntax
• A Simple Example of Inline Assembler
• Output Variables in Inline Assembler
• Input Variables in Inline Assembler
• Inlining Inline Assembler Code
• Other Asm Functionality

Other Asm Functionality

• The Clobber Parameter
• The Volatile Parameter