Gnat 3.12

Date of last revision: 05/18/2004

Gnat is an Ada compiler.


Platforms

Gnat is available on linux and Solaris workstations.

Conflicts


Preparation

Gnat uses standard setup scripts. The application name is "gnat" and this version is "gnat-3.12" (See "helpme setup" for instructions.)

Running


Running GNAT.
-------------
Three steps are needed to create an executable file from an Ada source file:
it must first be compiled, it then must go through the gnat binder, and then
all appropriate object files it needs are then linked together to produce an
executable.  A tool has been provided to combine the last 2 steps into one
command.

A small example.
----------------

The file hello.adb contains the source of our modest version of the
"Hello World" program.  Other components of this program are contained
in the GNAT Runtime Library (RTL).  You needn't mention the files
containing these other components but you can find the sources (g-io.ads,
g-io.adb, and a-cio.c) in the RTL source directory (described below).

The file hello.adb can be found in the current distribution in the examples
directory.  Here are the commands for building and running it (Since this
documentation is for systems running Unix and also for those running DOS,
IBM OS/2 2.x and Windows NT, in places where the instructions differ a prefix
"Unix:" or "OS/2:" or "DOS:" indicates what is relevant for each system):

            gcc -c hello.adb
            gnatbl -o hello hello.ali

create the executable called "hello" or "hello.exe" in your current directory.

In the example above, gnatbl calls the binder and creates a file b_hello.c
which contains among things the calls to the necessary elaboration procedures.
b_hello is then compiled and linked with all the other object files. After the
link is completed, both b_hello.c and b_hello.o (b_hello.obj) are removed by
default. If -g was specified on the call to gnatbl, the two files are not
removed since it is assumed they might be required for debugging.

Typing

      hello

will allow you to verify that the system is alive and willing to enter into 
a primitive dialogue.

The gcc switch -c indicates that we only want to compile, not link. The gnatbl
step produces the executable by means of calling the GNAT binder, compiling
its output, and calling gcc with the needed object files and libraries to
link the executable.  The -o switch is passed to the linker to name the
resulting executable file.

As the example suggests, the gcc command recognizes the extension .adb as
an indication of an Ada source file and calls the appropriate programs
to generate an object file (hello.o or hello.obj) and an Ada Library
Information (ALI) file (hello.ali) containing dependency information used
by the binder to verify consistency and determine order of elaboration.
The "ali" extension is recognized by gnatbl as the ALI file of the main
procedure or function, and gnatbl uses it to create a file called the
bind file, and to gather all the needed object files for linking.


Gnatbl
-----
  gnatbl
       [-o exec_name]
       [-v]                  -- verbose mode
       [-g]                  -- include debugging information
       [-linkonly]           -- doesn't call the binder
       [-gnatbind name]      -- full name for gnatbind
       [-gnatlink name]      -- full name for the linker (gcc)
       [list of objects]     -- non Ada binaries
       [linker options]      -- other options for the linker

The program gnatbl provides for binding and linking using the GNAT RTL.
Gnatbl calls gnatbind which creates a C file (b_hello.c in our
simple example) containing calls to all of the elaboration routines.
Gnatbind is described more fully below.  The typical use of GNAT (currently
-- in the presence of gnatbl) to construct a program consisting of a mix
of Ada and C sources is to compile all of the sources using "gcc -c" to
generate object (.o or .obj) files.  In the case of Ada sources, ALI files
with the extension .ali are also produced.  Then gnatbl is used to construct
the executable.  All arguments to gnatbl are simply passed through to gcc
to link the objects together, with the exception of a file name with the
.ali extension.  Such an argument is presumed to be the ALI file of the
main procedure of the program.  When gnatbl sees a .ali file it calls gnatbind
to create the bind file, compiles the bind file, extracts a list of needed
object files from the bind file, and replaces the .ali argument with the
a list of object files (the result of compiling the bind file and the list
extracted from the bind file) in the gcc command it makes.  As a quick
illustration consider a program comprising main.adb, foo.adb and bar.c.
After compiling these sources into object files, the command (under Unix)

gnatbl -o main main.ali bar.o

would cause gnatbl to:
  call "gnatbind main.ali", generating b_main.c
  call "gcc -c b_main.c"
  call "gcc -o main b_main.o main.o foo.o bar.o (+ gnat library args)"

In the last step, the "main.ali" argument has been replaced by all of the
object files needed by main (the binder file, main itself, and foo -- upon
which main depends). All other gnatbl arguments are passed through unchanged
to gcc.  Finally a -l and a -L argument are added to the end of the gcc call
to point it to the gnatlib library.  (Under OS/2, the command line and
behavior of gnatbl is similar.)  (Under DOS, the additional step of calling
"coff2exe main" is done.)

A current limitation of gnatbl is that the main program must be Ada and that
it depends on all of the necessary library units.  In other words, there can
be only one .ali file listed and it must be the main program. This
particularly restricts gnatbl's use when a routine written in another language
calls an Ada subprogram which is not also called from Ada.

[-o exec_name]
  Under unix if the -o option is omitted the executable is called the name of
  the main unit. So "gnatbl try.ali" will create an executable called try.
  Under DOS and OS/2 it would create an exectuable called try.exe.

[-v]
  The verbose option is most useful when the user wants to see what set of
  object files that are being used in the link step.

[-g]
  The option to include debugging information causes the C bind file, i.e.
  b_foo.c, to be compiled with -g. In addition the b_foo.c and b_foo.o file
  will not be removed (without -g the default action is to remove the binder
  generated files). Additionally on DOS, it causes the COFF output file to
  be preserved and on Windows NT causes extra debugging information to be
  linked into the executable.

[-linkonly]           -- doesn't call the binder
  Do not call gnatbind but rather use the bind file that has already been
  generated. This option is useful if the user wants to pass options to
  gnatbind which is not directly possible with gnatbl. The sequence would be:
  
  gnatbind binder_options file.ali
  gnatbl -linkonly file.ali

Options.
--------

Error reporting, as well as other aspects of the behavior of the system,
are controlled by the following flags. All of these must be entered with
the prefix '-gnat'. For example, '-gnatv83' specifies verbose mode for
output, and Ada83 syntax checking. 

  a	  Assertions enabled. Pragma Assert and Debug to be activated.
  b	  Generate brief messages to stderr even if verbose mode set.
  c	  Check syntax and semantics only (no code generation attempted)
  e	  Error messages generated immediately, not saved up till end
  f	  Full errors. Normally only the first error on each line is reported.
  g	  GNAT style checks enabled - col alignment, spacing, capitalization.
	  See any source file for examples.
  i?	  Identifier char set (?=1/2/3/4/8/p/f/n/w) default = i1 (Latin-1)
	    1-4 = Latin 1-4, p = IBM PC, f/n = full/no, upper w=wide_character
  j?      Wide character encoding method (?=n/h/u/s/e)
  knnn	  Limit file names to k characters (k = krunch)
  l	  Output full source listing with embedded error messages
  mnnn	  Limit number of detected errors to nnn (1-999)
  n	  Inlining of subprograms (apply pragma Inline across units)
  o       Enable integer overflow checking using range checks
  p	  Automatic suppression of all run-time checks mentioned in LRM 11.7
  q       Don't quit, try semantics, even if parse errors
  r	  Reference manual column layout required
  s	  Syntax check only
  t       Tree output file to be generated
  u	  List units for this compilation
  v	  Verbose mode. Full error output with source lines to stdout.
  w?	  Warning mode. s = suppress, e = treat as error
  x?      Cross-reference level and switches (?=1/2/3/4/5/9/b/s)
  z?      Distribution stub generation (r/s for receiver/sender stubs)
  83	  Enforce Ada 83 restrictions
  sfile	  Source file names (wild cards allowed for multiple files)

Some of these options are explained in more detail elsewhere in this document.
For full information, refer to file usage.adb in this distribution.

For first-time users, and for first-compilation attempts, the following mode
of operation is recommended:

      gcc -c -gnatc lets_try_this.adb


gnatmake
--------

In the following command line description we use BNF notation. Hence
[X] means zero or one occurrence of X, while {Y} means zero, one or
arbitrarily many occurrences of Y.

  gnatmake [-a] [-c] [-f] [-g] {[-Idir] [-Ldir]} [-n] [-q] [-s] [-v] 
           unit_or_file_name
           {[-cargs options] [-bargs options] [-largs options]}

The purpose of gnatmake is to automatically determine and (re)compile
the set of Ada sources needed by some ada compilation unit, Unit.  An
ada source needed by Unit is recompiled if its corresponding object
file is obsolete with respect to the current sources.  By default the
bind and link steps are also performed.

There are two ways to specify the actual compilation unit:

  * By giving the name of the compilation unit (`gnatmake Unit')
    (gnatmake is case insensitive when giving the unit name)

  * By giving the name of the source containing it
    ("gnatmake  file.adb" or "gnatmake  file.ads")

To decide whether gnatmake needs to recompile a source file, gnatmake
needs to locate other source files as well as the corresponding .ali
file. The search for source files is done in *exactly* the same
fashion as for gcc, whereas the search for .ali files is done
*exactly* like for the binder (both are described in the section on
search paths above). In particular the switch -I is directly available
in gnatmake (see below).

All gnatmake output is to stderr.

[-a]
   Consider all files. Considers all files in the make process, even
   the GNAT internal system files (for instance the predefined Ada
   library files). By default gnatmake does not check these internal
   files (don't worry this is safe, if there is an installation
   problem this will be caught when gnatmake binds your program).
   You may have to set this switch if you are working on gnat itself.
   For the vast majority of gnatmake users you never need to set this flag.

[-c]
   Compile only. Do not perform binding and linking. If the root unit specified
   by unit_or_file_name is not a main unit this is the default. Otherwise
   gnatmake will attempt linking and binding unless you have used "-c".

[-f]
   Force recompilations. Recompile all sources even though some object
   files may be up to date but don't recompile predifined units or GNAT
   internal files unless the -a switch is set.

[-g]
   Compile with debugging information. Same effect as -cargs -g -largs -g.
   See below for meaning of -cargs & -largs.

[-Idir]
   When looking for source or .ali files look also into directory
   "dir". The order in which source or .ali files search is
   undertaken is described in section search paths above. The -I
   switched is passed on to the compiler and the binder automatically
   so you need not type -cargs -Idir -bargs -Idir.  See below for
   the meaning of -cargs & -largs.

[-Ldir]
   Add directory "dir" to the list of directories in which gnatbl
   (actually ld) will search for libraries. This is equivalent to
   typing -largs -Ldir.  See below for the meaning of -largs.

[-n]
   Don't compile, bind or link. Checks if all objects are up to date.
   If they are "gnatmake -n" reports that no recompilations needed.
   Otherwise "gnatmake -n" stops printing out the full name of the first
   encoutered file that needs to be recompiled. Note that if you specify
   "-n -f" together, gnatmake will return the full name of the main unit.
        
[-q]
   Quiet. Without this flag set the commands carried out by gnatmake are
   displayed. If -q is set, they are not.

[-s]
   Smart. Performs smart recompilations. See section on smart gnatmake below.

[-v] 
   Verbose. Motivates all (re)compilations (ie gives *one* reason for
   (re)compiling a source file).

[-cargs options] 
   Compiler arguments. Without -cargs, gnatmake simply uses "gcc -c"
   to perform compilations. Otherwise gnatmake uses "gcc -c c_opts".
   "c_opts" is a list of parameters. This list includes all the
   options encoutered in the set of "-cargs options" present on the
   gnatmake command line. A given sublist of "-cargs options" is
   terminated upon encounter of another -cargs, -bargs or -largs.
   Note that by default "gnatmake -a" (see flag -a above) compiles all
   GNAT internal files with "gcc -c -gnatg" rather than just "gcc -c".
   
[-bargs options]
   Binder arguments. Without -bargs, gnatmake simply uses "gnatbind
   unit.ali" to bind. Otherwise gnatmake uses "gnatbind b_opts
   unit.ali". "b_opts" is akin to "c_opts" above but is obtained from
   "-bargs options".

[-largs options]
   Linker arguments.  Without -largs, gnatmake simply uses "gnatbl
   -linkonly unit.ali" to link. Otherwise gnatmake uses "gnatbl -linkonly
   l_opts unit.ali". "l_opts" is akin to "c_opts" and "b_opts" above but
   is obtained from "-largs options".

NOTES:

1. gnatmake examines both an ali file and its corresponding object file
for consistency. If an ali is more recent than its corresponding object,
or the object is missing, the corresponding source will be recompiled.
Note that gnatmake expects an ali and the corresponding object file
to be in the same directory.

2. Instead of typing a "-" in front of every switch you can group
switches. Thus, instead of typing "gnatmake -a -f" you can type
"gnatmake -af" Note, however, that the "-g" switch has to be on its
own to be recognized.

3. If there are no recompilations gnatmake tells you so, unless you've
used -q, in which case gnatmake is silent. Thus when you type
"gnatmake -n -q unit", gnatmake will either return the full path name
of the first file that needs to be recompiled, or it will be silent. Thus
"gnatmake -n -q" can be used as input to further tools.
  
4. If the user types "gnatmake file.adb" where file.adb is the body 
of a generic unit, then gnatmake will recompile file.adb systematically
because it finds no ali and then will stop. In particular take care that
in this case "gnatmake -n -q file.adb" will always return "file.adb".

5. If you gnatmake a spec that has a body (say "unit.ads") or a sub-unit
   you will get

       % gnatmake unit.ads
       gcc -c unit.ads
       No code generated for t1 (spec) in file t1.ads
       gnatmake: *** compilation failed.

   The compilation "fails" because specs or sub-units generate no
   code. To avoid the message use the -gnatc flag (semantics only).

       % gnatmake unit.ads -cargs -gnatc
       gcc -c -gnatc unit.ads

File Name Rules
---------------

The current version of GNAT requires that file names match compilation unit
names. The matching rules are as follows:

     o	The file name is obtained by replacing dots in the unit name with
	minus signs, and adding a suffix distinguishing bodies and specs.
	The suffix for specs is ".ads" and for bodies is ".adb".

	For example, files containing the unit very_long_unit_name would be
        called:

	    very_long_unit_name.ads
	    very_long_unit_name.adb

	on systems supporting long file names.

Ada Mode for Emacs
------------------

In the subdirectory `emacs-ada-mode' you will find a bunch of files
implementing an Ada mode under Gnu emacs. The mode is still under
development, but a number of features are complete. For instance, the
Ada mode has the same indenting friendliness that C programmers get
with the c-mode, you can toggle between spec and body with a few
keystrokes, etc. This mode also uses gnatf to be able to point to an
entity with the mouse, click it and open a window with its definition.
This mode is copywrited by Markus Heritsch and Rolf Ebert.


Click here to go back.