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: 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 the 17:title:`GNAT Studio documentation`. 18 19 20.. _System_Requirements: 21 22System Requirements 23=================== 24 25Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order 26to get the best experience, we recommend using a machine with as many cores 27as possible since all individual compilations can run in parallel. 28A comfortable setup for a compiler server is a machine with 24 physical cores 29or more, with at least 48 GB of memory (2 GB per core). 30 31For a desktop machine, a minimum of 4 cores is recommended (8 preferred), 32with at least 2GB per core (so 8 to 16GB). 33 34In addition, for running and navigating sources in GNAT Studio smoothly, we 35recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code. 36In other words, we recommend at least 3 GB for for 500K lines of code and 377.5 GB for 2 million lines of code. 38 39Note that using local and fast drives will also make a difference in terms of 40build and link time. Network drives such as NFS, SMB, or worse, configuration 41management filesystems (such as ClearCase dynamic views) should be avoided as 42much as possible and will produce very degraded performance (typically 2 to 3 43times slower than on local fast drives). If such slow drives cannot be avoided 44for accessing the source code, then you should at least configure your project 45file so that the result of the compilation is stored on a drive local to the 46machine performing the run. This can be achieved by setting the ``Object_Dir`` 47project file attribute. 48 49.. _Running_GNAT: 50 51Running GNAT 52============ 53 54Three steps are needed to create an executable file from an Ada source 55file: 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 61All three steps are most commonly handled by using the ``gnatmake`` 62utility program that, given the name of the main program, automatically 63performs the necessary compilation, binding and linking steps. 64 65.. _Running_a_Simple_Ada_Program: 66 67Running a Simple Ada Program 68============================ 69 70Any 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 72program.) 73The program text is a normal text file. We will assume in our initial 74example that you have used your editor to prepare the following 75standard 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 86This file should be named :file:`hello.adb`. 87With the normal default file naming conventions, GNAT requires 88that each file 89contain a single compilation unit whose file name is the 90unit name, 91with periods replaced by hyphens; the 92extension is :file:`ads` for a 93spec and :file:`adb` for a body. 94You can override this default file naming convention by use of the 95special pragma ``Source_File_Name`` (for further information please 96see :ref:`Using_Other_File_Names`). 97Alternatively, if you want to rename your files according to this default 98convention, which is probably more convenient if you will be using GNAT 99for all your compilations, then the ``gnatchop`` utility 100can be used to generate correctly-named source files 101(see :ref:`Renaming_Files_with_gnatchop`). 102 103You can compile the program using the following command (``$`` is used 104as 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 112capable of compiling programs in several languages, including Ada and 113C. It assumes that you have given it an Ada program if the file extension is 114either :file:`.ads` or :file:`.adb`, and it will then call 115the GNAT compiler to compile the specified file. 116 117The :switch:`-c` switch is required. It tells ``gcc`` to only do a 118compilation. (For C programs, ``gcc`` can also do linking, but this 119capability is not used directly for Ada programs, so the :switch:`-c` 120switch must always be present.) 121 122This compile command generates a file 123:file:`hello.o`, which is the object 124file corresponding to your Ada program. It also generates 125an 'Ada Library Information' file :file:`hello.ali`, 126which contains additional information used to check 127that an Ada program is consistent. 128 129To build an executable file, use either ``gnatmake`` or gprbuild with 130the name of the main file: these tools are builders that will take care of 131all the necessary build steps in the correct order. 132In particular, these builders automatically recompile any sources that have 133been modified since they were last compiled, or sources that depend 134on 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 142The result is an executable program called :file:`hello`, which can be 143run by entering: 144 145.. code-block:: sh 146 147 $ hello 148 149assuming that the current directory is on the search path 150for executable programs. 151 152and, if all has gone well, you will see:: 153 154 Hello WORLD! 155 156appear in response to this command. 157 158.. _Running_a_Program_with_Multiple_Units: 159 160Running a Program with Multiple Units 161===================================== 162 163Consider a slightly more complicated example that has three files: a 164main 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 194Following the one-unit-per-file rule, place this program in the 195following 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 210Note that there is no required order of compilation when using GNAT. 211In particular it is perfectly fine to compile the main program first. 212Also, it is not necessary to compile package specs in the case where 213there is an accompanying body; you only need to compile the body. If you want 214to submit these files to the compiler for semantic checking and not code 215generation, then use the :switch:`-gnatc` switch: 216 217.. code-block:: sh 218 219 $ gcc -c greetings.ads -gnatc 220 221Although the compilation can be done in separate steps, in practice it is 222almost always more convenient to use the ``gnatmake`` or ``gprbuild`` tools: 223 224.. code-block:: sh 225 226 $ gnatmake gmain.adb 227 228