1.. role:: switch(samp) 2 3.. _Getting_Started_with_GNAT: 4 5************************* 6Getting Started with GNAT 7************************* 8 9This chapter describes how to use GNAT's command line interface to build 10executable Ada programs. 11On most platforms a visually oriented Integrated Development Environment 12is also available, the GNAT Programming Studio (GNAT Studio). 13GNAT Studio offers a graphical "look and feel", support for development in 14other programming languages, comprehensive browsing features, and 15many other capabilities. 16For information on GNAT Studio please refer to 17:title:`Using the GNAT Programming Studio`. 18 19 20.. _Running_GNAT: 21 22Running GNAT 23============ 24 25Three steps are needed to create an executable file from an Ada source 26file: 27 28* The source file(s) must be compiled. 29* The file(s) must be bound using the GNAT binder. 30* All appropriate object files must be linked to produce an executable. 31 32All three steps are most commonly handled by using the ``gnatmake`` 33utility program that, given the name of the main program, automatically 34performs the necessary compilation, binding and linking steps. 35 36.. _Running_a_Simple_Ada_Program: 37 38Running a Simple Ada Program 39============================ 40 41Any text editor may be used to prepare an Ada program. 42(If Emacs is used, the optional Ada mode may be helpful in laying out the 43program.) 44The program text is a normal text file. We will assume in our initial 45example that you have used your editor to prepare the following 46standard format text file: 47 48 49.. code-block:: ada 50 51 with Ada.Text_IO; use Ada.Text_IO; 52 procedure Hello is 53 begin 54 Put_Line ("Hello WORLD!"); 55 end Hello; 56 57This file should be named :file:`hello.adb`. 58With the normal default file naming conventions, GNAT requires 59that each file 60contain a single compilation unit whose file name is the 61unit name, 62with periods replaced by hyphens; the 63extension is :file:`ads` for a 64spec and :file:`adb` for a body. 65You can override this default file naming convention by use of the 66special pragma ``Source_File_Name`` (for further information please 67see :ref:`Using_Other_File_Names`). 68Alternatively, if you want to rename your files according to this default 69convention, which is probably more convenient if you will be using GNAT 70for all your compilations, then the ``gnatchop`` utility 71can be used to generate correctly-named source files 72(see :ref:`Renaming_Files_with_gnatchop`). 73 74You can compile the program using the following command (``$`` is used 75as the command prompt in the examples in this document): 76 77.. code-block:: sh 78 79 $ gcc -c hello.adb 80 81 82``gcc`` is the command used to run the compiler. This compiler is 83capable of compiling programs in several languages, including Ada and 84C. It assumes that you have given it an Ada program if the file extension is 85either :file:`.ads` or :file:`.adb`, and it will then call 86the GNAT compiler to compile the specified file. 87 88The :switch:`-c` switch is required. It tells ``gcc`` to only do a 89compilation. (For C programs, ``gcc`` can also do linking, but this 90capability is not used directly for Ada programs, so the :switch:`-c` 91switch must always be present.) 92 93This compile command generates a file 94:file:`hello.o`, which is the object 95file corresponding to your Ada program. It also generates 96an 'Ada Library Information' file :file:`hello.ali`, 97which contains additional information used to check 98that an Ada program is consistent. 99To build an executable file, 100use ``gnatbind`` to bind the program 101and ``gnatlink`` to link it. The 102argument to both ``gnatbind`` and ``gnatlink`` is the name of the 103:file:`ALI` file, but the default extension of :file:`.ali` can 104be omitted. This means that in the most common case, the argument 105is simply the name of the main program: 106 107.. code-block:: sh 108 109 $ gnatbind hello 110 $ gnatlink hello 111 112A simpler method of carrying out these steps is to use ``gnatmake``, 113a master program that invokes all the required 114compilation, binding and linking tools in the correct order. In particular, 115``gnatmake`` automatically recompiles any sources that have been 116modified since they were last compiled, or sources that depend 117on such modified sources, so that 'version skew' is avoided. 118 119.. index:: Version skew (avoided by ``gnatmake``) 120 121.. code-block:: sh 122 123 $ gnatmake hello.adb 124 125The result is an executable program called :file:`hello`, which can be 126run by entering: 127 128.. code-block:: sh 129 130 $ hello 131 132assuming that the current directory is on the search path 133for executable programs. 134 135and, if all has gone well, you will see:: 136 137 Hello WORLD! 138 139appear in response to this command. 140 141.. _Running_a_Program_with_Multiple_Units: 142 143Running a Program with Multiple Units 144===================================== 145 146Consider a slightly more complicated example that has three files: a 147main program, and the spec and body of a package: 148 149 150.. code-block:: ada 151 152 package Greetings is 153 procedure Hello; 154 procedure Goodbye; 155 end Greetings; 156 157 with Ada.Text_IO; use Ada.Text_IO; 158 package body Greetings is 159 procedure Hello is 160 begin 161 Put_Line ("Hello WORLD!"); 162 end Hello; 163 164 procedure Goodbye is 165 begin 166 Put_Line ("Goodbye WORLD!"); 167 end Goodbye; 168 end Greetings; 169 170 with Greetings; 171 procedure Gmain is 172 begin 173 Greetings.Hello; 174 Greetings.Goodbye; 175 end Gmain; 176 177Following the one-unit-per-file rule, place this program in the 178following three separate files: 179 180 181 182*greetings.ads* 183 spec of package ``Greetings`` 184 185 186*greetings.adb* 187 body of package ``Greetings`` 188 189 190*gmain.adb* 191 body of main program 192 193To build an executable version of 194this program, we could use four separate steps to compile, bind, and link 195the program, as follows: 196 197.. code-block:: sh 198 199 $ gcc -c gmain.adb 200 $ gcc -c greetings.adb 201 $ gnatbind gmain 202 $ gnatlink gmain 203 204Note that there is no required order of compilation when using GNAT. 205In particular it is perfectly fine to compile the main program first. 206Also, it is not necessary to compile package specs in the case where 207there is an accompanying body; you only need to compile the body. If you want 208to submit these files to the compiler for semantic checking and not code 209generation, then use the :switch:`-gnatc` switch: 210 211.. code-block:: sh 212 213 $ gcc -c greetings.ads -gnatc 214 215Although the compilation can be done in separate steps as in the 216above example, in practice it is almost always more convenient 217to use the ``gnatmake`` tool. All you need to know in this case 218is the name of the main program's source file. The effect of the above four 219commands can be achieved with a single one: 220 221.. code-block:: sh 222 223 $ gnatmake gmain.adb 224 225In the next section we discuss the advantages of using ``gnatmake`` in 226more detail. 227 228.. _Using_the_gnatmake_Utility: 229 230Using the ``gnatmake`` Utility 231============================== 232 233If you work on a program by compiling single components at a time using 234``gcc``, you typically keep track of the units you modify. In order to 235build a consistent system, you compile not only these units, but also any 236units that depend on the units you have modified. 237For example, in the preceding case, 238if you edit :file:`gmain.adb`, you only need to recompile that file. But if 239you edit :file:`greetings.ads`, you must recompile both 240:file:`greetings.adb` and :file:`gmain.adb`, because both files contain 241units that depend on :file:`greetings.ads`. 242 243``gnatbind`` will warn you if you forget one of these compilation 244steps, so that it is impossible to generate an inconsistent program as a 245result of forgetting to do a compilation. Nevertheless it is tedious and 246error-prone to keep track of dependencies among units. 247One approach to handle the dependency-bookkeeping is to use a 248makefile. However, makefiles present maintenance problems of their own: 249if the dependencies change as you change the program, you must make 250sure that the makefile is kept up-to-date manually, which is also an 251error-prone process. 252 253The ``gnatmake`` utility takes care of these details automatically. 254Invoke it using either one of the following forms: 255 256.. code-block:: sh 257 258 $ gnatmake gmain.adb 259 $ gnatmake gmain 260 261The argument is the name of the file containing the main program; 262you may omit the extension. ``gnatmake`` 263examines the environment, automatically recompiles any files that need 264recompiling, and binds and links the resulting set of object files, 265generating the executable file, :file:`gmain`. 266In a large program, it 267can be extremely helpful to use ``gnatmake``, because working out by hand 268what needs to be recompiled can be difficult. 269 270Note that ``gnatmake`` takes into account all the Ada rules that 271establish dependencies among units. These include dependencies that result 272from inlining subprogram bodies, and from 273generic instantiation. Unlike some other 274Ada make tools, ``gnatmake`` does not rely on the dependencies that were 275found by the compiler on a previous compilation, which may possibly 276be wrong when sources change. ``gnatmake`` determines the exact set of 277dependencies from scratch each time it is run. 278