1.. _About_This_Guide:
2
3****************
4About This Guide
5****************
6
7.. only:: PRO
8
9   For ease of exposition, 'GNAT Pro' will be referred to simply as
10   'GNAT' in the remainder of this document.
11
12This manual contains useful information in writing programs using the
13GNAT compiler.  It includes information on implementation dependent
14characteristics of GNAT, including all the information required by
15Annex M of the Ada language standard.
16
17GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
18invoked in Ada 83 compatibility mode.
19By default, GNAT assumes Ada 2012,
20but you can override with a compiler switch
21to explicitly specify the language version.
22(Please refer to the *GNAT User's Guide* for details on these switches.)
23Throughout this manual, references to 'Ada' without a year suffix
24apply to all the Ada versions of the language.
25
26Ada is designed to be highly portable.
27In general, a program will have the same effect even when compiled by
28different compilers on different platforms.
29However, since Ada is designed to be used in a
30wide variety of applications, it also contains a number of system
31dependent features to be used in interfacing to the external world.
32
33.. index:: Implementation-dependent features
34
35.. index:: Portability
36
37Note: Any program that makes use of implementation-dependent features
38may be non-portable.  You should follow good programming practice and
39isolate and clearly document any sections of your program that make use
40of these features in a non-portable manner.
41
42What This Reference Manual Contains
43===================================
44
45This reference manual contains the following chapters:
46
47* :ref:`Implementation_Defined_Pragmas`, lists GNAT implementation-dependent
48  pragmas, which can be used to extend and enhance the functionality of the
49  compiler.
50
51* :ref:`Implementation_Defined_Attributes`, lists GNAT
52  implementation-dependent attributes, which can be used to extend and
53  enhance the functionality of the compiler.
54
55* :ref:`Standard_and_Implementation_Defined_Restrictions`, lists GNAT
56  implementation-dependent restrictions, which can be used to extend and
57  enhance the functionality of the compiler.
58
59* :ref:`Implementation_Advice`, provides information on generally
60  desirable behavior which are not requirements that all compilers must
61  follow since it cannot be provided on all systems, or which may be
62  undesirable on some systems.
63
64* :ref:`Implementation_Defined_Characteristics`, provides a guide to
65  minimizing implementation dependent features.
66
67* :ref:`Intrinsic_Subprograms`, describes the intrinsic subprograms
68  implemented by GNAT, and how they can be imported into user
69  application programs.
70
71* :ref:`Representation_Clauses_and_Pragmas`, describes in detail the
72  way that GNAT represents data, and in particular the exact set
73  of representation clauses and pragmas that is accepted.
74
75* :ref:`Standard_Library_Routines`, provides a listing of packages and a
76  brief description of the functionality that is provided by Ada's
77  extensive set of standard library routines as implemented by GNAT.
78
79* :ref:`The_Implementation_of_Standard_I/O`, details how the GNAT
80  implementation of the input-output facilities.
81
82* :ref:`The_GNAT_Library`, is a catalog of packages that complement
83  the Ada predefined library.
84
85* :ref:`Interfacing_to_Other_Languages`, describes how programs
86  written in Ada using GNAT can be interfaced to other programming
87  languages.
88
89* :ref:`Specialized_Needs_Annexes`, describes the GNAT implementation of all
90  of the specialized needs annexes.
91
92* :ref:`Implementation_of_Specific_Ada_Features`, discusses issues related
93  to GNAT's implementation of machine code insertions, tasking, and several
94  other features.
95
96* :ref:`Implementation_of_Ada_2012_Features`, describes the status of the
97  GNAT implementation of the Ada 2012 language standard.
98
99* :ref:`Obsolescent_Features` documents implementation dependent features,
100  including pragmas and attributes, which are considered obsolescent, since
101  there are other preferred ways of achieving the same results. These
102  obsolescent forms are retained for backwards compatibility.
103
104* :ref:`Compatibility_and_Porting_Guide` presents some guidelines for
105  developing portable Ada code, describes the compatibility issues that
106  may arise between GNAT and other Ada compilation systems (including those
107  for Ada 83), and shows how GNAT can expedite porting applications
108  developed in other Ada environments.
109
110* :ref:`gnu_fdl` contains the license for this document.
111
112.. index:: Ada 95 Language Reference Manual
113
114.. index:: Ada 2005 Language Reference Manual
115
116This reference manual assumes a basic familiarity with the Ada 95 language, as
117described in the
118:title:`International Standard ANSI/ISO/IEC-8652:1995`.
119It does not require knowledge of the new features introduced by Ada 2005 or
120Ada 2012.
121All three reference manuals are included in the GNAT documentation
122package.
123
124Conventions
125===========
126.. index:: Conventions, typographical
127
128.. index:: Typographical conventions
129
130Following are examples of the typographical and graphic conventions used
131in this guide:
132
133* ``Functions``, ``utility program names``, ``standard names``,
134  and ``classes``.
135
136* ``Option flags``
137
138* :file:`File names`
139
140* ``Variables``
141
142* *Emphasis*
143
144* [optional information or parameters]
145
146* Examples are described by text
147
148  ::
149
150    and then shown this way.
151
152* Commands that are entered by the user are shown as preceded by a prompt string
153  comprising the ``$`` character followed by a space.
154
155Related Information
156===================
157
158See the following documents for further information on GNAT:
159
160* :title:`GNAT User's Guide for Native Platforms`,
161  which provides information on how to use the
162  GNAT development environment.
163
164* :title:`Ada 95 Reference Manual`, the Ada 95 programming language standard.
165
166* :title:`Ada 95 Annotated Reference Manual`, which is an annotated version
167  of the Ada 95 standard.  The annotations describe
168  detailed aspects of the design decision, and in particular contain useful
169  sections on Ada 83 compatibility.
170
171* :title:`Ada 2005 Reference Manual`, the Ada 2005 programming language standard.
172
173* :title:`Ada 2005 Annotated Reference Manual`, which is an annotated version
174  of the Ada 2005 standard.  The annotations describe
175  detailed aspects of the design decision.
176
177* :title:`Ada 2012 Reference Manual`, the Ada 2012 programming language standard.
178
179* :title:`DEC Ada, Technical Overview and Comparison on DIGITAL Platforms`,
180  which contains specific information on compatibility between GNAT and
181  DEC Ada 83 systems.
182
183* :title:`DEC Ada, Language Reference Manual`, part number AA-PYZAB-TK, which
184  describes in detail the pragmas and attributes provided by the DEC Ada 83
185  compiler system.
186