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 distribution you are using is part of a growing body of freely-distributed 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.
This distribution contains three main components:
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 ("GNU's Not Unix") 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 excellent 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.
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. Other than these HTML documents, there are several important sets of documents in text form.
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 standard 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:\GNAT307, the GNAT and AdaCAPS documents are in C:\GNAT307\GW-GNAT\DOCS.
GNAT itself is described in GNATINFO.TXT and its HTML version, the GNAT Users Guide; all the details of AdaCAPS are to be found in ADACAPS.DOC.
You need an IBM PC Compatible, 80386, 80486, or Pentium, running MS-DOS or PC-DOS; testing has been done with DOS 5 or greater. It is best to have hardware-provided floating point arithmetic, not software-emulated floating point. Pentiums all have hard floating-point; 80486DX models do but 80486SX models (many laptops) do not. 80386 models can be equipped with an 80387 floating point chip. If you do not have hardware floating point, many programs will work anyway, but some -- especially programs that use Ada tasks or other services from the tasking runtime -- may "crash" with a DOS exception. Ther is no workaround for this, except to acquire more modern hardware.
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 Windows 3.1 user, we suggest that you get started with ez2load by quitting Windows and running from a "pure" DOS system. Move to Windows 3.1 later, after you know what to expect from DJGPP and GNAT.
You need 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.
You need 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), please read the document netinstl.doc in the gw-gnat\docs directory.
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.
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 directory 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.
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 the GNAT User Manual.
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.
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.
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
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:
To give you an idea of the output produced by a traceback, here is a sample run. In this case, we have compiled
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, suppose the user types 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, 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 -- 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. #4 rationals."/" (x=1, y=0) at rational.adb:48 #5 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>
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. For your convenience we have included a GDB manual in this html directory.