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