Copyright (C) 1992 Irvine Compiler Corporation
                   34 Executive Prak, Suite 270
                   Irvine CA 92714, USA

Everyone is permitted to copy and distribute verbatim copies of this
software as long as this document is distributed with it, but changing
it is not allowed.

All rights to this C header file to Ada source translator are
reseverved by Irvine Compiler Corporation.  It has been provided free
of charge without support and without any obligation on the part of
Irvine Compiler.

THIS SOFTWARE IS PROVIDED "AS IS" WITH NO WARRANTIES OF ANY KIND
INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A
PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR
TRADE PRACTICE.

If you have any problems, bugs, or have suggestions, please send
mail to mark@irvine.com.



c2ada/cfront

Revision: v1.0.2
  Author: Mark Schimmel


This is the second release of this translator.  It my hope that it
soon will be provided in source form free of charge.


REVISION ENHANCEMENTS

Added support for C const vars.
Added floating point support.
Fixed Ada/83 record field naming errors.
Changed -Dname defines to have a value of 1.
Added -version flag to support patch identification.


RATIONALE

The C programming language enjoys an enormous amount of popularity
thanks to its free distribution with the Unix operating systems and to
its early acceptance among the accedemic community.  That being the
case there is a large amount of useful software, libraries and
algorithms that are freely available to C programmers.  I'd like to
provide a means of making that software base easily accessible to the
Ada community as well.



PORTING

This translator generates some types that are not immediately portable
to all Ada compilers.  However, most of the generated types are
subtypes from the package C provided in this distribution.  The very
first thing you will need to do before the generated Ada code will
compile is retarget package C to your compiler.  Don't worry about
getting all the unsigneds correct before you start playing with the
translator, just make sure the sizes of the types are correct.  You'll
be able to lookup all the nasty compiler hacks at a later time.



IMPLEMENTATION

This version of the translator is basically a parser for the ansi C
type system.  It also includes a built in C preprocessor that attempts
to make macro definitions available to the Ada community as well.

A major ATTEMPT was made to maintain the exact names from the original
C source.  This is not always possible.

I prefer a loose type system so most types generated by the translator
will follow that philosophy.  It feels like the "right thing" to do
when the language you are interfacing to is so relaxed.  I'm quite
sure this will be a point of contention to many in the Ada community.
There already appears to me to be two factions;  those who derive
everything and those who are forced to cast cast cast cast cast :-).

Anyway, back to the particulars.  Unions, unsigneds and function
pointers are not supported by all Ada compilers.  The code generated
by this translator targets the ICC Ada compiler and will be particular
to it in this release (like I said I'd like to make the sources
available for others to port to verdix, dec, mips, rational ...).


Unions:
        Unions are implemented as records whose fields are overlayed
via rep specs.  The overlaying of fields via rep specs is not allowed
in the Ada language.  However, most compilers realize that it is a
very useful thing to do and will have some mechanism that supports it.
I have already received and rejected feedback from some who'd like to
see this become some sucky variant record.  Sorry to those of you who
hold that opinion but a C union is not an Ada variant record.

        union u1 {
                int field1;
                char *field2;
        };

        type u1 is
           record
              field1: int;
              field2: char_p;
           end record;

        for u1 use
           record
              field1 at 0 range 0 .. 31;
              field2 at 0 range 0 .. 31;
           end record;


Unsigneds:
        Unsigned integers are supported by most compilers through some
mechanism or another.  They are generated by this translator as
subtypes to a type from the package C.  Once you get the package C
ported properly unsigned integers should work just fine.

Function Pointers:
        Function pointers are subtypes of system.address and loose
their prototype information (parameters and return type).  This is
unfortunate, but I haven't yet thought of a good way around it.  I'm
open to any and all suggestions.

Type aliasing:
        C has a very forgiving type system.  This translator attempts
to model that behavior.  I have gotten some good feedback here about
generating derived types from typedefs and will be incorporating that
into the next release.


Anonymous types:
        One important thing that I'd like to mention here in defense
of the current implementation is that user type names are preferred
over generated type names.  For example:


        extern char *p1;
        
        struct s {
                char *p2;
        };
        
        typedef char *caddr_t;
        
        
        type s;
        
        type caddr_t is access char;
        
        type s is
           record
              p2: caddr_t;
           end record;
        
        p1: caddr_t;
        pragma interface(c, p1);


I have received negative feedback from many who don't like the fact
that variables with anonymous types (as in p1 and p2) will have their
types promoted to another type.  The reason this is done is to avoid
compiler generated type names.  In the above example the compiler
could have generated some type name for the anonymous char * types of
p1 and p2.  This was not done because the user provided a type name
with a base type of char *.  My contention with compiler generated
type names is that if I use them you will have to go searching through
the output to find the names the translator chose.  If instead you
provide a low level typedef scheme of your own, you can be assured
that the translator will choose your names, which I think is a more
deterministic approach.
