htod.dd

Ddoc

$(D_S htod,

$(MESSAGE_BOX orange, $(B Warning) - `htod` is not developed actively.
    Please see $(LINK2 https://wiki.dlang.org/Bindings#Binding_generators,
    Binding generators on the D Wiki) for a list of alternatives.)


$(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
        converting 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)

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

$(H3 Usage)

$(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 $(D //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 $(D #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 $(D #include <file>) 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/sc.html, dmc).
)
)

)

$(H3 Example)

$(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 MYINT = int;
void  bar(int x, int y, long z);
---

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

$(H3 Type Mappings)

$(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.
)

        $(TABLE
        <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)

$(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 Wherever
        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)

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

        $(LI No Linux version.)
)

)

Macros:
        TITLE=htod
        SUBNAV=$(SUBNAV_CLI_REFERENCE)