RISC DISC 1/RISC_DISC_1.iso/pd_share/code/ada/!Ada/doc/adaed

Text File | 1994-08-28 | 16.2 KB | 505 lines

ADAED - 4 August 1992, NYU Ada Group, Unix Programmer's Manual

NAME

adaed - NYU translator and interpreter for the Ada programming language

SYNOPSIS

 adacomp [ option ] ... `file'
 adabind [ option ]
 adaexec [ option ]
 adalib  [ -l `library' ]

DESCRIPTION

Adaed is a translator/interpreter for the Ada programming language
that is intended primarily for educational use.

Adacomp compiles an Ada program; it invokes in succession the two
compilation phases: parsing and semantic analysis (the front end), and code
generation. The `file' argument refers to the source file; if it contains no
suffix the Ada source is assumed to be in `file.ada'. It may be a full path
name. The output of the compiler is an instruction stream for an abstract
Ada machine, which is subsequently interpreted.

Adabind binds a given `library' with the specified `main_unit' to form an
executable program.

Adaexec invokes the Ada machine interpreter for the bound program given in
the specified library.

Adalib is a utility that enables the user to examine the contents of the
specified library.

Note: all options must precede the file name for `adacomp' and must be in
lower case.

LIBRARY

All compilations require a library.

A library is a subdirectory, which is created or reinitialized when the user
invokes a command containing `-n' option, such as:

    adacomp -n -l libname adafile

Intermediate files appear in subdirectory `libname'.

This directory is created by the command if it does not already exist. Only
the listing files are created in the directory from which `adacomp' is
invoked.

The `libname' directory should be used to hold files created by the `adaed'
commands only (i.e. those produced by the Ada/Ed system); confusion and
grief may result if you attempt to use a library directory to hold other
files. The `libname' argument may be a full path name.

If the environment variable ADALIB is defined, its value is used as a
default library and the `-l' option (including its `libname' argument) to
`adacomp, adabind, adaexec,' and `Iadalib' can be omitted.

A given utility library, UL (e.g. one that contains mathematical functions)
may be used by several unrelated programs. It may then be convenient to
create independent libraries for each program, and initialize each library
with the contents of UL. This can be done simply by creating directories for
each library, and copying the contents of UL into each of these.

OPTIONS

The options for `adacomp' are as follows:

 -a Generates instructions for use by the interpreter (`adaexec' command) to
    trace the Ada source lines. Used in conjunction with the `-t a' option of
    `adaexec'.

 -b Indicates that the binding of the library is to be performed if the
    current compilation is completed without errors.

 -g Specifies that the compiler is to produce a listing of the generated
    instructions for the Ada machine (of little interest to most users).

 -i x
    This is an option to the binder and is relevant only if the `-b' option
    is used.

See options for `adabind' below.

 -l library
    Uses the specified library to satisfy references to compilation units
    not present in the file being compiled. If the compilation is successful,
    the units defined in the file are added to the library. If this option
    is not specified explicitly, a default library is implicitly defined by
    the ADALIB environment variable.

 -m unit_name
    This is an option to the binder and is relevant only if the `-b' option
    is used.

See options for `adabind' below.

 -n Indicates that a new library is to be created for this compilation. The
    name of the library is indicated by the `-l' option or through the
    ADALIB environment variable. The `-n' option must be specified if the
    library referenced by the `-l' option (or the ADALIB environment variable)
    does not already exist or must be reinitialized.

 -s Produces a listing of the source file. The name of the listing file is
    the input file name prefix with suffix `.lis'. By default, no listing
    file is generated unless there are warnings, errors or informational
    messages to report.

 -v Gives a (verbose) descriptive trace showing the subsidiary programs
    invoked by the `adacomp' command, the options and arguments passed to them,     and their exit status. This is used primarily for system checkout.

The options for `adabind' are as follows:

 -l library
    Specifies the library which together with the main unit will produce a
    bound program which can be executed by `adaexec'. If this option is not
    specified explicitly, a default library is implicitly defined by the
    ADALIB environment variable.

 -m unit_name
    Specifies the name of the unit which is to serve as a main program. When
    the library contains only one main program (which must be a parameterless
    procedure) this option is not needed.

 -i x
    To be used for programs that use `pragma' INTERFACE. `x' designates the
    non-Ada interfaced procedures and may be

    a) the name of an object file, created by the user, of the form
       `filename.o' (that appears in the same directory as the Ada program);
  or

    b) an abbreviation for the library '/lib/lib`x'.a'. If that does not exist
       then '/usr/lib/lib`x'.a' is searched. This library is unrelated to the
       Ada program library referenced by the various `adaed' commands, and
       generally refers to a standard library provided for another programming
       language. This option may be used as many times as necessary, providing
       that each use represents only a single file or library. Thus,
       `adabind -i a.o -i b.o -i lib ...' is acceptable, while
       `adabind -i a.o b.o lib ...' is not. To use this option, the environment
       variable INT must be set to point to the directory containing the file
       `adaint' (see the Setup file or your system manager). Usage examples
       appear below.

The options for `adaexec' are as follows:

 -l library
    Specifies the library which contains the bound program to be executed.
    If this option is not specified explicitly, a default library is
    implicitly defined by the ADALIB environment variable.

 -m bound_main_unit
    Specifies the name of the bound main unit, i.e. the main unit
    that was specified to `adabind', or `adacomp'. Note that a given
    library may have been bound several times with different main units.
    When the library has been bound with only one main unit, this option
    is not needed.

 -h heap_size
    Specify the size of the heap increment in kilowords, by which the heap is
    expanded when the elaboration of a new entity requires it. The heap expands
    to fill available memory. The default increment is 128. This parameter
    limits the size of the largest object that can be created in a program.


 -p p_size
    Specifies the size in bytes of the program stack size for the main task.
    The default is 10000. Argument values in the range 1..31 are multiplied
    by 1024 to obtain the stack size in bytes. The maximum value is 32767.

 -s t_size
    Specifies the size in bytes of the stack size for each new task. The
    default is 10000. Argument values in the range 1..31 are multiplied by
    1024 to obtain the stack size in bytes. Use of small stack sizes may be
    appropriate when executing programs with many tasks, each of which can
    run with a small stack. The maximum value is 32767.

 -r number_of_stmts (an integer)
    Invoke a 'round-robin' scheduling policy instead of the 'run-until-block'
    default scheduling policy and specify the maximum number of interpreted
    statements that a given task can execute before switching to another
    task (the minimum value is 1).

 -t trace_options
    Specify one or more of the following letters indicating the kind of
    trace(s) requested for the execution of the program.

    a    (Ada line)
         Display the source line numbers. This requires that the program be
         compiled with the `-a' option.

    c    (calls)
         Display the name of each subprogram as it is entered and exited.

    e    (exceptions)
         Display the name of each exception as it is raised.

    r    (rendezvous)
         Trace each rendezvous.

    s    (switches)
         Display context switches between tasks.

    t    (tasks)
         Display task creation, activation, and termination.


EXAMPLES

The following examples show typical usage:

1) Compile t1.ada into a new library called testlib and bind the library;
   then execute it.The listing is written to t1.lis. Note that `-s' is used
   to force a listing file to be created.

    adacomp -s -nl testlib -b t1

    adaexec -l testlib

2) Compile a package specification in p.spc and corresponding body in p.bod
   into a new library called tstlib. Then compile t2.ada into the same
   library, bind the main program, and execute it

    adacomp -nl tstlib p.spc

    adacomp -l tstlib p.bod

    adacomp -l tstlib -b t2

    adaexec -l tstlib

3) In the example above, the binding could be done in a separate phase. This
   is achieved by replacing the third command above with:

    adacomp -l tstlib t2

    adabind -l tstlib

4) Example 2 above could be done without explicitly specifying the library
   by setting the environment variable ADALIB, as follows:

    setenv ADALIB my_default_directory

    adacomp -n p.spc

    adacomp p.bod

    adacomp -b t2

    adaexec

5) Compile a program with line numbers included in the generated code.
   Execute it displaying Ada source line numbers as they are encountered.

    adacomp -a -nl libname -b t1

    adaexec -t a -l libname

6) Compile a program with two parameterless procedures (potential main
   programs) which are named MAIN1 and MAIN2 in files p1.ada and p2.ada
   respectively, and bind the library tstlib using MAIN1 as the main
   program.

    adacomp -nl tstlib p1

    adacomp -l tstlib p2

    adabind -m main1 -l tstlib

    adaexec -l tstlib

7) Suppose we wish to add another program to the library tstlib (created in
   Example 6) whose main program unit is named MAIN3 and appears in file
   p3.ada. The following commands will compile and execute MAIN3. As tstlib
   was previously bound with MAIN1 as a main unit, it is now necessary to
   use the `-m' option to adaexec in order to select the desired bound main
   unit.

    adacomp -l tstlib p3

    adabind -m main3 -l tstlib

    adaexec -m main3 -l tstlib

8) The contents of the library above can be examined by:

    adalib -l tstlib

Adalib writes the name, type and compilation date of each unit in the
specified library to standard output. In addition, it writes the current
status (active or obsolete) of each unit. Units which may be main programs
are noted by "(Main)"; if there is more than one such unit, the `-m' option to
adabind must be specified during binding. Libraries that have been bound
will contain at least one unit labeled "binding unit". If several of these
are active, the `-m' option must be specified for adaexec.


PRAGMA INTERFACE

Pragma interface (LRM 13.9) is currently supported for interfacing to
subprograms written in FORTRAN or C.

Arguments to interfaced procedures must be one of the following types:

For C: integer, float, access, array, record, and enumeration types.
For FORTRAN: integer, float and array.

The return types available are integer and float.

Following are sample Ada programs that are interfaced to subprograms coded
in FORTRAN and C, together with the code for the interfaced subprograms:

1) Interface to FORTRAN


 This is a source file called `func.f' which contains two functions to be used
 in an Ada program with pragma INTERFACE.

     function sqr(x)
     sqr = x*x
     return
     end

     function cube(x)
     cube = x*x*x
     return
     end

 -- Assume that the following are the contents of file `fortlib.ada'.
 -- It contains a compilation unit that defines two functions which are
 -- interfaced to the above routines.

 package FORTRAN_LIB is
     function SQR(X:FLOAT) return FLOAT;
     function CUBE(X:FLOAT) return FLOAT;
 private
     pragma INTERFACE(FORTRAN, SQR);
     pragma INTERFACE(FORTRAN, CUBE);
 end FORTRAN_LIB;

 with FORTRAN_LIB, TEXT_IO; use FORTRAN_LIB, TEXT_IO;
 procedure TEST is
    function SQRT(X : FLOAT) return FLOAT;
    pragma INTERFACE(C,SQRT);
    package MY_FLOAT_IO is new FLOAT_IO(FLOAT); use MY_FLOAT_IO;
 begin
     PUT(SQR(2.0));
     NEW_LINE;
     PUT(CUBE(2.0));
     NEW_LINE;
     PUT(SQRT(2.0));
     NEW_LINE;
 end TEST;

To compile and execute, enter the following commands:

    f77 -c func.f

    adacomp -nl testlib -b -i func.o fortlib

    adaexec -l testlib

The output will be:
 4.00000E+00
 8.00000E+00
 1.41421E+00

One of the demo programs illustrates how one can use pragma interface
to build a library of mathematical functions from those provided by the
system.

2) Interface to C


/*
 * Source file proc.c contains procedures PRINTA and PRINTS1 called by
 * the Ada program above.
 */
 printa(ara)
 int ara[];
 {
    int i;
    for (i=0;i<10;i++) {
       printf("%d ",ara[i]);
    }
    printf("\\n");
 }

prints1(ara,len)
 int ara[];
 int len;
 {
    int i;
    for (i=0;i<len;i++) {
        printf("%c",ara[i]);
    }
    printf("\\n");
 }

-- Assume that file `test_interface.ada' contains the following program:
 procedure C_INTERFACES is
     type ARA10 is array(1..10) of INTEGER;
     A10: ARA10 := (1,2,3,4,5,6,7,8,9,10);

     procedure PRINTA(A:ARA10);
     -- PRINTA prints an array of 10 elements of type INTEGER
     pragma INTERFACE(C, PRINTA);

     procedure PRINTS1(A:STRING; LEN: INTEGER);
     -- PRINTS1 prints an array of LEN elements of type CHARACTER
     pragma INTERFACE(C, PRINTS1);

     procedure PRINTS(A:STRING) is
     -- This routine prints a string by passing the string and its length
     -- to the routine PRINTS1 which is written in C.
     begin
         PRINTS1(A, A'length);
     end;

 begin
    PRINTA(A10);
    PRINTS("this is any string");
 end;


To compile and execute, enter the following:

    cc -c proc.c

    adacomp -i proc.o -nl testlib -b test_interface

    adaexec -l testlib

The resulting output is as follows:

 1 2 3 4 5 6 7 8 9 10
 this is any string


ENVIRONMENT

The environment variable ADALIB contains the name of the library used if
none is specified on the command line.

Normally the executables called by adacomp and the predefined libraries are
in a directory built into the system. The directory containing these can be
specified by the environment variable ADAED which overrides the built in
directory name.

The location of individual components called by adacomp or the location of
the predefined libraries can be overridden with the following environment
variables:

  ADAFRONT    - For the front end, adafront;
  GEN         - For the code generator, adagen;
  BND         - For the binder, adabind;  and
  ADAEDPREDEF - For the predefined libraries."

FILES

file.ada    Ada source file
adaint        partially built interpreter (used for pragma interface)
predef.axq    symbol table for predef
predef.trc    tree file for predef
predef.lib    library for predef

DIAGNOSTICS

Adaed commands return an exit code of 0 in the case of success, and nonzero
otherwise. An error code of 1 indicates errors in usage of the Ada language,
2 is returned if there is an internal Adaed system error, and 3 denotes some
invalid usage of the Adaed system. Error messages regarding invalid system
usage are directed to the standard error file. Ada language related messages
detected at compilation are written to the listing file, while those
detected by adabind or adaexec appear on standard output.

Note, that an error in a given compilation unit may cause subsequent
compilation units (within the same compilation) not to be recognized.

AUTHORS

Ada/Ed-C was written by the following members of the NYU Ada Project:
Bernard Banner, Jerome Chiabaut, Robert Dewar, Anne Dinning, Alain Lauque,
Gail Schenker Morgulis, Brett Porter, Jean-Pierre Rosen, Edmond Schonberg,
David Shields, Brian Siritzky, Franck Triplet.

BUGS

We give absolutley no warranty as to the correctness of the system. It was
designed strictly for teaching purposes. Currently it is unvalidated although
we hope to put it in a validatable shape in the near future.

Any compilation or execution that terminates abnormally with mention of
"internal error" has uncovered a bug that should be reported to the NYU Ada
group.

NYUADA project
New York University
251 Mercer Street
New York, N.Y. 10012
(212) 998 \- 3480