Debian Codegraph @

gcc/ada/doc/gnat_rm/about_this_guide.rst

raw
1 .. _About_This_Guide:
2
3 ****************
4 About 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
12 This manual contains useful information in writing programs using the
13 GNAT compiler. It includes information on implementation dependent
14 characteristics of GNAT, including all the information required by
15 Annex M of the Ada language standard.
16
17 GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
18 invoked in Ada 83 compatibility mode.
19 By default, GNAT assumes Ada 2012,
20 but you can override with a compiler switch
21 to explicitly specify the language version.
22 (Please refer to the *GNAT User's Guide* for details on these switches.)
23 Throughout this manual, references to 'Ada' without a year suffix
24 apply to all the Ada versions of the language.
25
26 Ada is designed to be highly portable.
27 In general, a program will have the same effect even when compiled by
28 different compilers on different platforms.
29 However, since Ada is designed to be used in a
30 wide variety of applications, it also contains a number of system
31 dependent features to be used in interfacing to the external world.
32
33 .. index:: Implementation-dependent features
34
35 .. index:: Portability
36
37 Note: Any program that makes use of implementation-dependent features
38 may be non-portable. You should follow good programming practice and
39 isolate and clearly document any sections of your program that make use
40 of these features in a non-portable manner.
41
42 What This Reference Manual Contains
43 ===================================
44
45 This 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:`Security_Hardening_Features` documents GNAT extensions aimed
100 at security hardening.
101
102 * :ref:`Obsolescent_Features` documents implementation dependent features,
103 including pragmas and attributes, which are considered obsolescent, since
104 there are other preferred ways of achieving the same results. These
105 obsolescent forms are retained for backwards compatibility.
106
107 * :ref:`Compatibility_and_Porting_Guide` presents some guidelines for
108 developing portable Ada code, describes the compatibility issues that
109 may arise between GNAT and other Ada compilation systems (including those
110 for Ada 83), and shows how GNAT can expedite porting applications
111 developed in other Ada environments.
112
113 * :ref:`gnu_fdl` contains the license for this document.
114
115 .. index:: Ada 95 Language Reference Manual
116
117 .. index:: Ada 2005 Language Reference Manual
118
119 This reference manual assumes a basic familiarity with the Ada 95 language, as
120 described in the
121 :title:`International Standard ANSI/ISO/IEC-8652:1995`.
122 It does not require knowledge of the new features introduced by Ada 2005 or
123 Ada 2012.
124 All three reference manuals are included in the GNAT documentation
125 package.
126
127 Conventions
128 ===========
129 .. index:: Conventions, typographical
130
131 .. index:: Typographical conventions
132
133 Following are examples of the typographical and graphic conventions used
134 in this guide:
135
136 * ``Functions``, ``utility program names``, ``standard names``,
137 and ``classes``.
138
139 * ``Option flags``
140
141 * :file:`File names`
142
143 * ``Variables``
144
145 * *Emphasis*
146
147 * [optional information or parameters]
148
149 * Examples are described by text
150
151 ::
152
153 and then shown this way.
154
155 * Commands that are entered by the user are shown as preceded by a prompt string
156 comprising the ``$`` character followed by a space.
157
158 Related Information
159 ===================
160
161 See the following documents for further information on GNAT:
162
163 * :title:`GNAT User's Guide for Native Platforms`,
164 which provides information on how to use the
165 GNAT development environment.
166
167 * :title:`Ada 95 Reference Manual`, the Ada 95 programming language standard.
168
169 * :title:`Ada 95 Annotated Reference Manual`, which is an annotated version
170 of the Ada 95 standard. The annotations describe
171 detailed aspects of the design decision, and in particular contain useful
172 sections on Ada 83 compatibility.
173
174 * :title:`Ada 2005 Reference Manual`, the Ada 2005 programming language standard.
175
176 * :title:`Ada 2005 Annotated Reference Manual`, which is an annotated version
177 of the Ada 2005 standard. The annotations describe
178 detailed aspects of the design decision.
179
180 * :title:`Ada 2012 Reference Manual`, the Ada 2012 programming language standard.
181
182 * :title:`DEC Ada, Technical Overview and Comparison on DIGITAL Platforms`,
183 which contains specific information on compatibility between GNAT and
184 DEC Ada 83 systems.
185
186 * :title:`DEC Ada, Language Reference Manual`, part number AA-PYZAB-TK, which
187 describes in detail the pragmas and attributes provided by the DEC Ada 83
188 compiler system.