root/trunk/docsrc/htod.dd

Ddoc

$(D_S htod,

$(P While D is binary compatible with C code, it cannot
    compile C code nor C header files. In order for
    D to link with C code, the C declarations residing
    in C header files need to be converted to a D
    module. $(B htod) is a migration tool to aid in
    convering C header files.
)
$(P $(B htod) is built from the front end of the Digital
    Mars C and C++ compiler. It works just like a C or
    C++ compiler except that its output is a D module
    rather than object code.
)
$(P The macro $(B __HTOD__) is predefined and set to $(B 1),
    which is handy for improving C header files to give better
    D output.
)

<h3>Download</h3>

$(P $(LINK2 http://ftp.digitalmars.com/htod.zip, htod)
)

<h3>Usage</h3>

$(GRAMMAR
$(B htod) $(I cheader.h) [$(I dimport.d)] [$(B -cpp)] [$(B -hc)] [$(B -hi)] [$(B -hs)] [$(B -ht)] { $(I C compiler switches) }
)

$(P where:)

$(DL

$(DT $(I cheader.h)
$(DD C or C++ header input file
)
)

$(DT $(I dimport.d)
$(DD D source code output file (defaults to $(I cheader).d)
)
)

$(DT $(B -cpp)
$(DD Indicates a C++ header file
)
)

$(DT $(B -hc)
$(DD By default, $(B htod) will insert the C and C++ declarations
in a file into the output file prefixed by $(TT //C     ).
$(B -hc) will suppress this.
Use only if you're confident that $(B htod) is generating the
correct output file (such as if the header file was modified with
$(B __HTOD__)).
)
)

$(DT $(B -hi)
$(DD By default, $(B htod) will represent a $(TT #include "file") with
a corresponding $(B import) statement. The $(B -hi) will cause the
declarations in the included file to be converted to D declarations as
well. The declarations in all included files are parsed regardless.
$(B -hi) is handy when replacing an entire hierarchy of include files
with a single D import.
System includes like $(TT #include &lt;file&gt;) are not affected
by $(B -hi).
See also $(B -hs).
)
)

$(DT $(B -ht)
$(DD By default, $(B htod) will write types using typedef names as
using those names. $(B -ht) will cause the underlying types to be
used instead. This is very useful for "drilling down" layers of
macros, typedefs, and #includes to find out the underlying type.
)
)

$(DT $(B -hs)
$(DD Works just like $(B -hi), except that system includes are
migrated as well.
)
)

$(DT $(I C compiler switches)
$(DD C or C++ compiler switches, such as $(B -D) and $(B -I) as documented
for $(LINK2 http://www.digitalmars.com/ctg/dmc.html, dmc).
)
)

)

<h3>Example</h3>

$(P The C test.h file:)

$(CCODE
unsigned u;
#define MYINT int
void bar(int x, long y, long long z);
)

$(P Translated with:)

$(CONSOLE
htod test.h
)

$(P Produces the file test.d:)

---
/* Converted to D from test.h by htod */
module test;
//C     unsigned u;
extern (C):
uint u;
//C     #define MYINT int
//C     void bar(int x, long y, long long z);
alias int MYINT;
void  bar(int x, int y, long z);
---

$(P The C declarations are prefixed by the string $(TT "//C     ").)

<h3>Type Mappings</h3>

$(P C types are mapped as follows. These mappings are correct
    for Digital Mars C/C++, but may not be correct for your
    C compiler. D basic types have fixed sizes, while C basic
    type sizes are implementation defined.
)

    $(TABLE1
    <caption>Mapping C to D types</caption>
    $(TR $(TH C type) $(TH D type))
    $(TR $(TD void) $(TD void))
    $(TR $(TD _Bool) $(TD bool))
    $(TR $(TD wchar_t) $(TD wchar))
    $(TR $(TD char) $(TD char))
    $(TR $(TD signed char) $(TD byte))
    $(TR $(TD unsigned char) $(TD ubyte))
    $(TR $(TD short) $(TD short))
    $(TR $(TD unsigned short) $(TD ushort))
    $(TR $(TD int) $(TD int))
    $(TR $(TD unsigned) $(TD uint))
    $(TR $(TD long) $(TD int))
    $(TR $(TD unsigned long) $(TD uint))
    $(TR $(TD long long) $(TD long))
    $(TR $(TD unsigned long long) $(TD ulong))
    $(TR $(TD float) $(TD float))
    $(TR $(TD double) $(TD double))
    $(TR $(TD long double) $(TD real))
    $(TR $(TD _Imaginary float) $(TD ifloat))
    $(TR $(TD _Imaginary double) $(TD idouble))
    $(TR $(TD _Imaginary long double) $(TD ireal))
    $(TR $(TD _Complex float) $(TD cfloat))
    $(TR $(TD _Complex double) $(TD cdouble))
    $(TR $(TD _Complex long double) $(TD creal))
    )

<h3>Limitations</h3>

$(P There is no one to one correspondence of C declarations
    to D declarations. A review of the D module output will
    be necessary to ensure the right decisions are made.
    Furthermore:
)

$(OL
    $(LI Whereever
    practical, C headers should be written using $(B typedef)'s and
    $(B enum)'s rather than macros.
    $(B htod) will attempt to convert simple macro $(B #define)'s
    to $(B alias) and $(B const) declarations.
    Even so, macros are fully expanded before further analysis.)

    $(LI No attempt is made to convert C conditional compilation
    into D $(B version) or $(B static if) declarations.)

    $(LI No output is generated for false conditional compilation
    sections.)

    $(LI $(B htod) converts declarations only, it does not convert
    C code.)

    $(LI Declarations with C++ linkage cannot be converted.
    A C interface must be made for any C++ code.)

    $(LI C language extensions present in the C .h file
    may not be recognized.)

    $(LI Pragmas are not translated.)

    $(LI The tag names are assumed to not collide with
    names in the regular name space.)

    $(LI Any character data that is not ASCII will need
    to be converted as necessary to UTF.)

    $(LI The C $(B char) type is assumed to map to the
    D $(B char) type. However, these should be examined individually
    to see if they should instead be translated to $(B byte) or
    $(B ubyte) types. Whether the C $(B char) type is signed or
    unsigned is implementation defined. The D $(B char) type
    is unsigned.)

    $(LI Named C enum members are not inserted into the surrounding
    scope as they are in C.)

    $(LI D modules are each in their own name space, but C
    header files are all in the same global name space. This means
    that D references to names defined in other modules may
    need to be qualified.)
)

<h3>Bugs</h3>

$(OL
    $(LI Anything other than the default struct member
    alignment is not accounted for.)

    $(LI No Linux version.)
)

)

Macros:
    TITLE=htod
    WIKI=htod