CBIND(1)CBIND(1)NAME
cbind - a tool to aid in the creation of Ada bindings to C
SYNOPSIS
cbind [options] C source files
DESCRIPTION
Cbind will read C source and include files and will generate Ada pack‐
ages containing translations of the types and function prototypes which
it read. The output can serve as a thin binding to the original C
source. You may also want a thicker binding. In this case the tool
may be able to do a lot of the grunt work for you.
WARNING: Be very careful to obey any copyright on the original source.
By default, all the types and subprogram specs will be lumped into one
Ada package. Use the -ap switch to get the tool to generate multiple
packages automatically.
CBIND recognizes the following switches:
-Dname
-Dname=value
Define a macro with an optional value. By default macros will be
defined with the value 1. Synonymous with -D on most C preproces‐
sors.
-Uname
Undefine a builtin macro. Synonymous with -U on most C preproces‐
sors.
-Idir
Add a search path for finding include files. Synonymous with -I
on most C preprocessors.
-builtin
Display all predefined macros. The macros are defined in macro.c.
If you are missing anything you should add it at the top of this
source file.
-p Run the preprocessor and send the output to stdout. This is help‐
ful when cbind botches something.
-s Show commands that would get invoked but don't actually do them.
-fun Flag all union declarations as they are generated to the output
files.
-cs Add sizeof and alignof comments for all declarations. This is
useful when porting cbind to different platforms. If the sizeof
or alignof information is incorrect the resulting binding will
also be erroneous. The sizeof and alignof functions can be found
in types.c.
-erc Always generate enum representation clauses. If your Ada compiler
does not generate enumeration ordinals the same as your C compiler
you will need this option.
-sih Suppress import declarations from included headers. Normally
cbind will subtype from directly included headers in order to han‐
dle things the way C would. For example, most people include sig‐
nal.h to get the signal ordinals, but the ordinals are usually
defined in sys/signal.h. In order to be able to with signal_h and
get the signal ordinals cbind normally includes declarations from
sys/signal.h in the package signal_h. Clear as mud?
-hex Prefer to generate numeric values in hexidecimal. The base in
which the constant was originally declared in has been boiled
away. Thus, cbind must rely on other methods for determining when
to use decimal, octal or hexidecimal.
-src Suppress all record representation clauses. This is a very ugly
flag which allows the Ada compiler to immediately compile bindings
to C unions. The binding will not strictly match the C source,
but sometimes you just want things to compile.
-rrc Always generate record representation clauses. If your Ada com‐
piler doesn't lay out records the same way that C lays out structs
you will need this option.
-ap Automatic packaging. This is the golden egg option. It causes
cbind to automatically generate a package for every file it
encounters. If you do not like the package naming mechanism you
can change the routines in units.c.
-C Attempt to retain C comments in the translation. See the BUGS
section below.
-cf Attempt to translate C macros into Ada functions if possible. See
the BUGS section below for limitations.
-rational
Specify Rational as the target Ada compiler. Cbind will generate
different pragmas when it knows which target compiler you are
using.
-vads
Specify verdix as the target Ada compiler. Cbind will generate
different pragmas when it knows which target compiler you are
using.
-icc Specify Irvine Compiler as the target Ada compiler. Cbind will
generate different pragmas when it knows which target compiler you
are using.
ENVIRONMENT
No environment variables are used by cbind.
CAVEATS
In most instances where C unions are declared they will be nested
within a struct and discriminated by some enumerated type. Unfortu‐
nately cbind cannot tell how unions are discriminated and if it could
it still wouldn't know which fields in the union correspond to which
values of the discriminant. Therefore, it is highly unlikely that
cbind will ever be able to generate the appropriate Ada variant records
for you. Many Ada compilers will not allow fields in a record to over‐
lap because it's not allowed by the language. These are the same com‐
pilers that will generally give you unsigned types, function pointers
and macro preprocessors. Anyway, If your Ada compiler is like mine
you'll want to use the -fun switch and handle unions yourself.
There are many include files like /usr/include/signal.h which are used
extensively, but whose real definitions are in a nested include file
like /usr/include/sys/signal.h. Cbind will generate 2 packages, one
for /usr/include/signal.h and one for /usr/include/sys/signal.h named
signal_h and sys_signal_h respectively. Since it would be less helpful
to force the user to with both packages all the defined types and con‐
stants from sys_signal_h are subtyped in signal_h. Sometimes this
negitively affects the generated binding. Cbind really doesn't know
when to do the subtyping and renaming and when to suppress it. There
is an option -sih which will suppress the inclusion of these declara‐
tions but you have to manually control it.
BUGS
Could be a lot smarter about name conflicts. Currently when a C iden‐
tifier is an Ada reserved word or cbind has already seen the identifier
it will generate a fairly ugly unique name for it.
I'd like to do a much better job with C comments. The reason it hasn't
been done already is because it's difficult. For one, I have to gener‐
ate things out of order to obey the Ada type declaration system. Once
things are out of order it becomes real hard to get the comments to
come out reasonably.
There are many limitations to functions that can be created when the
-cf option is used. The way cbind figures this out is it passes 1 for
all the parameters for the C macro. If a reasonable result is found
after evaluating the macro then it will generate a function.
SEE ALSOcc(1)cpp(1)
LOCAL CBIND(1)