DragonFly On-Line Manual Pages
CBIND(1) DragonFly General Commands Manual 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
packages 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
preprocessors.
-Uname
Undefine a builtin macro. Synonymous with -U on most C
preprocessors.
-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
helpful 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
handle things the way C would. For example, most people include
signal.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
compiler 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.
Unfortunately 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 overlap because it's not allowed by the language. These are the
same compilers 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
constants 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
declarations but you have to manually control it.
BUGS
Could be a lot smarter about name conflicts. Currently when a C
identifier 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
generate 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 ALSO
cc(1) cpp(1)
LOCAL CBIND(1)