FILE:

EZ2LOAD.DOC

GW-GNAT Distribution January 1997

Using the GW-GNAT EZ2Load Distribution for GNAT 3.07
---------------------------------------------------Prof. Michael B. Feldman
Department of Electrical Engineering and Computer Science
The George Washington University
Washington, DC 20052
(202) 994-5919 (voice)
(202) 994-0227 (fax)
mfeldman@seas.gwu.edu (Internet)
Purpose
------The purpose of this document is to guide you in using the
GNAT Ada 95 compiler and the other tools in the GW ez2load
distribution. This document does NOT teach Ada 95; we assume that
you have access to an Ada 95 textbook and/or online tutorial.
The Joy of Free Software
-----------------------The distribution you are using is part of a growing body of freelydistributed software. Unlike proprietary software, which is usually
developed within a single company, free software is produced by
dedicated people working independently at their own sites. Considering
the geographic dispersion and varied talents of these developers,
free software shows a quite amazing degree of coherence and
integration.
Free software "packaging", however, is not usually what we've
come to expect from proprietary developers. To use free software
effectively, you must be prepared to work with collections of
components from different places and people, each with its own
volume and style of documentation, mostly in electronic form.
For the most part, there are no nicely printed and expensively
bound user manuals for free software.
Which main components are in this distribution?
---------------------------------------------This distribution contains three main components:
- GNAT, the Ada 95 compiler and binder;
- DJGPP, the underlying OS services, C compiler, assembler, and linker;
- AdaCAPS, the integrated development environment (IDE).
GNAT
---GNAT is a full Ada 95 compiler and binder produced originally at
New York University and now maintained by Ada Core Technologies (ACT),
a commercial company in New York City. Many ACT employees were
members of the original GNAT team at NYU.
GNAT is one of the large family of GNU tools sometimes called "gcc"
(though gcc itself is really nothing but a driver program that invokes
other tools). An advantage of the GNU structure is the portability it
provides: there are GNU code generators for nearly every computer platform,
and the various GNU compilers produce intermediate code that is then
processed through the appropriate GNU code generator. This leads to
another advantage: The various GNU languages interoperate smoothly.

It is very easy and straightforward, for example, to mix Ada 95

code with C code, and not much harder to interface Ada 95 with
C++ code.
The DOS version of GNAT is built on a DOS version of gcc called DJGPP;
the "DJ" part of the name refers to the original author, DJ Delorie.
Charles W. Sandmann also contributed heavily. This freely distributable
system provides many UNIX-like services to the DOS world, but most
important, it gives DOS users a 32-bit environment with virtual memory
management. The DJGPP system is very large and rich; GNAT/DOS is
distributed with a minimal DJGPP called djgpp200.zip.
The ez2load IDE is called AdaCAPS, and comes from Ken Price of
Pepperell, Massachusetts. The general look and feel is that of the
familiar Borland DOS development environments. The commands and
keystrokes are simple and intuitive, and there is ample online help.
AdaCAPS is supported by a suite of programs, sometimes called the
GW-GNAT suite, developed by Charles Kann and Michael Feldman of
The George Washington University, Washington, DC.
There is also a hypertext Ada 95 Reference Manual, for which
we are indebted to Arthur Vargas Lopes of Porto Alegre, Brazil.
Key Documents
------------The components described above were developed independently, and
each has its own documentation. The document you are reading is
an attempt to give you some guidance in using the various components,
but not to duplicate other documents.
The DJGPP documents are installed in a docs subdirectory of the
top-level GNAT directory, that is, if the top-level GNAT directory
is C:\GNAT307, the DJGPP documents are in C:\GNAT307\DOCS. The
most important DJGPP document is the frequently-asked-questions
file, DJGPPFAQ.TXT. This is a lengthy document, very rich in
information. Item 9 and its sub-items is especially useful if
you experience unexpected crashes or register dumps. CWSDPMI.DOC
is also useful; it describes the dpmi memory manager provided
with DJGPP. (CWS is Charles W. Sandmann, author of the
memory manager.)
To avoid mixing too many documents from different sources,
the GNAT and AdaCAPS documents are installed separately. If
you installed GNAT and the other tools at the same time,
the installer will have created, in the top level GNAT
directory, a subdirectory GW-GNAT, under which is a DOCS
subdirectory. Thus if your GNAT directory is C:\GNAT,
the GNAT and AdaCAPS documents are in C:\GNAT\GW-GNAT\DOCS.
GNAT itself is described in GNATINFO.TXT; all the details of
AdaCAPS are to be found in ADACAPS.DOC.
System Requirements
------------------You need:
- IBM PC Compatible, 386 or 486, running MS-DOS or PC-DOS;
testing has been done with DOS 5 or greater.

We have done some testing using the DOS mode of Windows 95,
and using a Windows 95 DOS window; everything seems to
operate successfully in those modes. If you have problems,
try booting DOS by pressing F4 at system startup, before
Windows 95 has a chance to start.
If you are a
started with
a "pure" DOS
know what to

Windows 3.1 user, we suggest that you get

ez2load by quitting Windows and running from
system. Move to Windows 3.1 later, after you
expect from DJGPP and GNAT.

- at least 4 mb available extended memory (you will find

that performance is VERY slow with less than 8 mb RAM)
If you have at least 8 mb RAM, you will find a huge
speedup in performance if you make sure to use the DOS
smartdrv operation to set up a disk cache of at least 2mb
Check your DOS manual on how to install this.
- at least 21 mb free hard disk space for the software;
it is also advisable to have at least 10 mb of space
available for DJGPP's virtual memory swap file.
We do not have facilities to test the components in a network
environment; if you are operating in such an environment
(a university lab, for example), we will greatly appreciate
your writing us (e-mail preferred) to describe your successes
and/or difficulties.
Installation
-----------We assume you have a complete ez2load distribution, consisting of
at least:
- two installer programs, GINSTALL.EXE and DINSTALL.EXE.
GINSTALL installs from hard disk or CD-ROM; DINSTALL installs
from diskettes.
- the installer script file, INSTALL.SCR.
- the mini-DJGPP, DJGPP200.ZIP
- the four GNAT files, GNAT3071.ZIP - GNAT3074.ZIP
- the IDE and tools file, ACAPS22.ZIP (possibly the last digit
will be higher than 5, if we release a newer IDE version).
In using DJGPP, GNAT, and AdaCAPS, it is important to ensure that
the path and envirinment variables are set correctly. The installation
program creates a DOS command script (batch file), named GNAT307.BAT
by default. This batch file sets up the necessary environment.
You need to execute this batch file before running any of the components.
To ensure that this happens automatically, you can copy the batch file
into your AUTOEXEC.BAT, or simply add a call to GNAT307 as the last
line of your AUTOEXEC.BAT.
Once you are set up, change directories to a working directories
which contains, or will contain, your Ada 95 programs, then
type

adacaps
and the IDE will start. We give no further details here on
AdaCAPS; refer to the online help or ADACAPS.DOC.
GNAT/DOS File Names
------------------To use GNAT without difficulty, you must make sure that your
Ada unit (program or package) name agrees with its file name
(except that the file name should be in lower case). Further,
a package specification should have an .ads (Ada Specification)
file extension and any other unit should have an .adb (Ada Body)
extension.
A main program My_Prog should be in a file called my_prog.adb.
A package My_Pack should be divided into my_pack.ads and
my_pack.adb. When you are first getting started, keep your
program and package names at 8 or fewer characters, so that
the DOS file names will match exactly. When you gain experience,
you can learn GNAT's rules for converting longer unit names
into 8+3 file names. These rules appear in GNATINFO.TXT.
The GW-GNAT Suite of Programs: GCOMPILE, GLINK, GEXECUTE
-------------------------------------------------------AdaCAPS handles compilation, linking, and execution by invoking
the appropriate GW-GNAT program. These programs encapsulate the
most common options, and provide automatically for listing files
and debugging support.
These programs can also be executed from the DOS command line,
so we describe them here. Used consistently, these programs make
it easy for new users to get started with GNAT. To use these,
you must first have executed the batch file described above.
Compiling
--------To compile a program, say My_Prog, in a file my_prog.adb, type
gcompile my_prog.adb
Whether or not there are any compilation errors, gcompile
always produces a listing file for your program unit.
(In a class environment, this ensures that your listing is
always consistent with your compiled code.) An .ads source
files produces a .lss listing file; an .adb file produces
an .lsb listing file.
GNAT produces, as part of its compilation output, a .o (object
code) and an .ali file. The .ali files are used by the binder
to check package dependencies.
Binding and Linking
------------------In Ada, binding is the process of checking the consistency of
the set of program units making up an executable. Linking is
the process of actually producing the executable from its
component object modules (including those from the Ada
run time libraries).

The GW-GNAT suite combines these stages into a single command.

Given a compiled main program, say My_Prog, type
glink my_prog.ali
Note that you supply the .ali, not the source, file name.
This will produce two files, my_prog.exe and my_prog.cof.
my_prog.exe is an executable file which can be directly run
like any DOS program. To run it, just type
my_prog
myprog.cof is a COFF format file. In DJGPP, COFF format files are
required for debugging with a debugger (in our case, GDB);
gexecute uses GDB to produce an automatic traceback in case of an
unhandled Ada exception, and therefore requires a COFF file.
To run your program with exception tracing turned on, type
gexecute my_prog.cof
NOTE: This version of gexecute is a batch file, gexecute.bat,
which calls AD, the new GDB interface from Gautier de Montmollin.
The old gexecute.exe is still in the directory, under the name
gexecute.old. If you have trouble with the new interface,
you can restore the old one. Go to your gw-gnat directory,
rename gexecute.bat to something else (save.bat, maybe) and
rename gexecute.old to gexecute.exe.
Relationship between AdaCAPS and the GW-GNAT Programs
---------------------------------------------------AdaCAPS calls gcompile to compile a program unit.
AdaCAPS calls glink to bind a link a main program.
AdaCAPS behavior when Run is selected depends upon the
execution option selected from the Options menu:
N (normal) AdaCAPS opens a file window showing *.exe files,
and just executes the selected file
T (traceback) AdaCAPS opens a file window showing .cof files, and
calls gexecute with the selected file
D (debug) AdaCAPS opens a file window showing .cof files, and
calls GDB with the selected file. You are placed in the
GDB command shell, and you are on your own.
A Sample Run with a gexecute Traceback
-------------------------------------To give you an idea of the output produced by a traceback,
here is a sample run. In this case, we have compiled
- a package Rationals that provides operations on rational numbers;
- a child package Rationals.IO that provides Get and Put
operations on rationals;

- a main program Test_Rationals_1 that executes a few operations.

These program units are available in the cs2code directory,
assuming you installed these programs from the distribution.
Let's assume you installed the programs in C:\CS2CODE.
When prompted to enter a rational quantity, the user typed 1 0,
which would attempt to place a 0 in the denominator of a rational.
This is mathematically unacceptable, so the package raises an
exception ZeroDenominator. Here is the sample run.
C:\CS2CODE>gexecute tesrati1.cof
Running tesrati1.cof
A = 1/3
B = -1/2
Enter rational number C > 1 0
raised RATIONALS.ZERODENOMINATOR
---- Call stack ----------File
Line Unit
--------------------------------------------------------------------rational.adb
48 Rationals
"/"(x=1, y=0)
.....................................................................
rationio.adb
26 Rationals.IO
get(file=0x1ea40, item={numerator = 0, denominator = 1})
.....................................................................
rationio.adb
34 Rationals.IO
get(item={numerator = 0, denominator = 1})
.....................................................................
tesrati1.adb
34 Test_Rationals_1
.....................................................................
Program terminated
C:\CS2CODE>
Here is the same sample run, using the old gexecute.exe, which we have
annotated with Ada-style comment lines.
C:\CS2CODE>gexecute tesrati1.exe
Program tesrati1.exe is not an ".cof" file, cannot be run
-- gexecute gives an error message if file is not .cof
C:\CS2CODE>gexecute tesrati1.cof
Running tesrati1.cof
-- the next line is output by GDB and cannot be suppressed
Breakpoint 1: file a-raise.c, line 65.
-- the next 3 lines were displayed by the executing program
A = 1/3
B = -1/2
Enter rational number C > 1 0
***UNHANDLED EXCEPTION RAISED - TRACEBACK FOLLOWS***
-- lines #0 through #3 trace back from locations in the GNAT runtime
-- system. They cannot be suppressed; ignore them
#0 __gnat_unhandled_exception (except=) at a-raise.c:65
#1 __gnat_raise_nodefer_with_msg (except=) at a-raise.c:108

#2 __gnat_raise_nodefer (except=) at a-raise.c:120

#3 __gnat_raise (except=) at a-raise.c:130
-----#4
#5

lines #4 through #7 are the important ones.

They show that the exception was raised in Rationals."/",
which was called by the file-oriented Rationals.IO.Get,
which was called by the interactive Rationals.Io.Get,
which was called by Test_Rationals_1.
rationals."/" (x=1, y=0) at rational.adb:48
rationals.io.get (file=, item={numerator = 0, denominator = 1})
at rationio.adb:26
#6 rationals.io.get (item={numerator = 0, denominator = 1})
at rationio.adb:34
#7 test_rationals_1 () at tesrati1.adb:34
-- ignore lines #8 and #9, which reflect the Ada 95 environment
-- from which Test_Rationals_1 was called.
#8 main (argc=1, argv=, envp=) at b_tesrati1.c:36
#9 __crt1_startup ()
***END OF TRACEBACK***
raised RATIONALS.ZERODENOMINATOR
Program exited with code 01.
go32_close called
C:\CS2CODE>
Using GDB with the GW-GNAT Tools
-------------------------------If you wish to try GDB itself, remember that you need to use
a .cof file, as with gexecute. Type
gdb my_prog.cof
and you will be placed in the GDB command shell. Once you are
inside GDB, typing
help
will give you some brief online help. GDB is a very powerful
debugger with lots of commands and options. Full GDB documentation
is available in the HTML documentation archive included with
the ez2load distribution.