Copyright (C) 1992 Irvine Compiler Corporation
                   34 Executive Park, 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
reserved 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.3
  Author: Mark Schimmel


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


REVISION ENHANCEMENTS

Added builtin pointer types
Added -repspec
Fixed a bug in record field bitoffset calculation
Added -package and c2ada.lib
Fixed problems with function pointers in formal decls
Changed union/struct/enum naming
Changed anonymous union/struct/enum naming



RELEASE NOTES

The directory structure of this release has changed.  The Makefile in
this directory can be used to install this tool.  I have moved the
Xlib example to examples/X, and added a binding to /usr/include which
can be found in examples/unix.


This release adds one major feature that I've received requests for
and that is to implement a packaging/Ada library feature to the
translator.  C2ada will now generate packages from .h files if your
give it the -package qualifier.  The best documentation is to look in
the example/unix directory.  I generate incomplete bsd'ish bindings
to /usr/include.

A quick explanation of how things work is that each time you run the
translator with the -package qualifier it will keep tract of all it
sees and store them along with the Ada package it generated in the
c2ada.lib file.  The next time you run the translator it will check
all the types it sees with what it has seen previously, and if it
already has seen the declaration it will with the appropriate Ada
package and generate code accordingly.

The translator will now keep track of what is has seen in the file
c2ada.lib which it generates in the current directory when you run it.
It is very possible to get the c2ada.lib file in a state which causes
the translator to generate circular Ada dependencies.  When that
happens the only thing you can do is delete the c2ada.lib file and
re-make.

When running the translator with -package you'll notice a significant
reduction in performance.  This is a consequence of the new feature
which doesn't seriously affect the performance of running without
-package.  Hopefully the gain is worth the cost.



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 academic 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.
