Debian Codegraph @

gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst

raw
1 .. role:: switch(samp)
2
3 .. _Getting_Started_with_GNAT:
4
5 *************************
6 Getting Started with GNAT
7 *************************
8
9 This chapter describes how to use GNAT's command line interface to build
10 executable Ada programs.
11 On most platforms a visually oriented Integrated Development Environment
12 is also available: GNAT Studio.
13 GNAT Studio offers a graphical "look and feel", support for development in
14 other programming languages, comprehensive browsing features, and
15 many other capabilities.
16 For information on GNAT Studio please refer to the
17 :title:`GNAT Studio documentation`.
18
19
20 .. _System_Requirements:
21
22 System Requirements
23 ===================
24
25 Even though any machine can run the GNAT toolset and GNAT Studio IDE,
26 to get the best experience we recommend using a machine with as many cores
27 as possible, allowing individual compilations to run in parallel.
28 A comfortable setup for a compiler server is a machine with 24 physical cores
29 or more, with at least 48 GB of memory (2 GB per core).
30
31 For a desktop machine, we recommend a minimum of 4 cores (8 is preferred),
32 with at least 2GB per core (so 8 to 16GB).
33
34 In addition, for running and smoothly navigating sources in GNAT Studio, we
35 recommend at least 1.5 GB, plus 3 GB of RAM per million source lines of code.
36 So we recommend at least 3 GB for 500K lines of code and
37 7.5 GB for 2 million lines of code.
38
39 Using fast, local drives can make a significant difference in build
40 and link times. You should avoid network drives such as NFS, SMB, or
41 worse, configuration management filesystems (such as ClearCase dynamic
42 views) as much as possible since these will produce very degraded
43 performance (typically 2 to 3 times slower than on fast, local
44 drives). If you cannot avoid using such slow drives for accessing
45 source code, you should at least configure your project file so
46 the result of the compilation is stored on a drive local to the
47 machine performing the compilation. You can do this by setting the
48 ``Object_Dir`` project file attribute.
49
50 .. _Running_GNAT:
51
52 Running GNAT
53 ============
54
55 You need to take three steps to create an executable file from an Ada
56 source file:
57
58 * You must compile the source file(s).
59 * You must bind the file(s) using the GNAT binder.
60 * You must link all appropriate object files to produce an executable.
61
62 You most commonly perform all three steps by using the ``gnatmake``
63 utility program. You pass it the name of the main program and it automatically
64 performs the necessary compilation, binding, and linking steps.
65
66 .. _Running_a_Simple_Ada_Program:
67
68 Running a Simple Ada Program
69 ============================
70
71 You may use any text editor to prepare an Ada program.
72 (If you use Emacs, an optional Ada mode may be helpful in laying out the
73 program.)
74 The program text is a normal text file. We will assume in our initial
75 example that you have used your editor to prepare the following
76 standard format text file named :file:`hello.adb`:
77
78
79 .. code-block:: ada
80
81 with Ada.Text_IO; use Ada.Text_IO;
82 procedure Hello is
83 begin
84 Put_Line ("Hello WORLD!");
85 end Hello;
86
87 With the normal default file naming conventions, GNAT requires
88 that each file
89 contain a single compilation unit whose file name is the
90 unit name with periods replaced by hyphens; the
91 extension is :file:`ads` for a
92 spec and :file:`adb` for a body.
93 You can override this default file naming convention by use of the
94 special pragma ``Source_File_Name`` (see :ref:`Using_Other_File_Names`).
95 Alternatively, if you want to rename your files according to this default
96 convention, which is probably more convenient if you will be using GNAT
97 for all your compilations, then you use can use the ``gnatchop`` utility
98 to generate correctly-named source files
99 (see :ref:`Renaming_Files_with_gnatchop`).
100
101 You can compile the program using the following command (``$`` is used
102 as the command prompt in the examples in this document):
103
104 .. code-block:: sh
105
106 $ gcc -c hello.adb
107
108
109 ``gcc`` is the command used to run the compiler. It is
110 capable of compiling programs in several languages, including Ada and
111 C. It assumes you have given it an Ada program if the file extension is
112 either :file:`.ads` or :file:`.adb`, in which case it will call
113 the GNAT compiler to compile the specified file.
114
115 The :switch:`-c` switch is required. It tells ``gcc`` to only do a
116 compilation. (For C programs, ``gcc`` can also do linking, but this
117 capability is not used directly for Ada programs, so you must always
118 specify the :switch:`-c`.)
119
120 This compile command generates a file
121 :file:`hello.o`, which is the object
122 file corresponding to your Ada program. It also generates
123 an 'Ada Library Information' file :file:`hello.ali`,
124 which contains additional information used to check
125 that an Ada program is consistent.
126
127 To build an executable file, use either ``gnatmake`` or ``gprbuild`` with
128 the name of the main file: these tools are builders that perform
129 all the necessary build steps in the correct order.
130 In particular, these builders automatically recompile any sources that have
131 been modified since they were last compiled, as well as sources that depend
132 on such modified sources, so that 'version skew' is avoided.
133
134 .. index:: Version skew (avoided by ``gnatmake``)
135
136 .. code-block:: sh
137
138 $ gnatmake hello.adb
139
140 The result is an executable program called :file:`hello`, which you can
141 run by entering:
142
143 .. code-block:: sh
144
145 $ hello
146
147 assuming that the current directory is on the search path
148 for executable programs.
149
150 and, if all has gone well, you will see::
151
152 Hello WORLD!
153
154 appear in response to this command.
155
156 .. _Running_a_Program_with_Multiple_Units:
157
158 Running a Program with Multiple Units
159 =====================================
160
161 Consider a slightly more complicated example with three files: a
162 main program and the spec and body of a package:
163
164
165 .. code-block:: ada
166
167 package Greetings is
168 procedure Hello;
169 procedure Goodbye;
170 end Greetings;
171
172 with Ada.Text_IO; use Ada.Text_IO;
173 package body Greetings is
174 procedure Hello is
175 begin
176 Put_Line ("Hello WORLD!");
177 end Hello;
178
179 procedure Goodbye is
180 begin
181 Put_Line ("Goodbye WORLD!");
182 end Goodbye;
183 end Greetings;
184
185 with Greetings;
186 procedure Gmain is
187 begin
188 Greetings.Hello;
189 Greetings.Goodbye;
190 end Gmain;
191
192 Following the one-unit-per-file rule, place this program in the
193 following three separate files:
194
195
196
197 *greetings.ads*
198 spec of package ``Greetings``
199
200
201 *greetings.adb*
202 body of package ``Greetings``
203
204
205 *gmain.adb*
206 body of main program
207
208 Note that there is no required order of compilation when using GNAT.
209 In particular it is perfectly fine to compile the main program first.
210 Also, it is not necessary to compile package specs in the case where
211 there is an accompanying body; you only need compile the body. If you want
212 to submit these files to the compiler for semantic checking and not code
213 generation, use the :switch:`-gnatc` switch:
214
215 .. code-block:: sh
216
217 $ gcc -c greetings.ads -gnatc
218
219 Although you can do the compilation in separate steps, in practice it's
220 almost always more convenient to use the ``gnatmake`` or ``gprbuild`` tools:
221
222 .. code-block:: sh
223
224 $ gnatmake gmain.adb
225