betterc.dd

Ddoc

$(SPEC_S Better C,

$(HEADERNAV_TOC)

    $(P It is straightforward to link C functions and libraries into D programs.
    But linking D functions and libraries into C programs is not straightforward.
    )

    $(P D programs generally require:)

    $(OL
    $(LI The D runtime library to be linked in, because many features of
    the core language require runtime library support.)
    $(LI The `main()` function to be written in D, to ensure that the required
    runtime library support is properly initialized.)
    )

    $(P To link D functions and libraries into C programs, it's necessary to only
    require the C runtime library to be linked in. This is accomplished by defining
    a subset of D that fits this requirement, called $(B BetterC).
    )

    $(IMPLEMENTATION_DEFINED $(B BetterC) is typically enabled by setting the $(TT -betterC)
    command line flag for the implementation.
    )

    $(P When $(B BetterC) is enabled, the predefined $(LINK2 version.html, version) `D_BetterC`
    can be used for conditional compilation.
    )


    $(P An entire program can be written in $(B BetterC) by supplying a C `main()` function:)

    ---
    extern(C) void main()
    {
        import core.stdc.stdio : printf;
        printf("Hello betterC\n");
    }
    ---

$(CONSOLE
$(GT) dmd -betterC hello.d && ./hello
Hello betterC
)

    $(P Limiting a program to this subset of runtime features is useful
    when targeting constrained environments where the use of such features
    is not practical or possible.
    )

    $(P $(B BetterC) makes embedding D libraries in existing larger projects easier by:
    )

    $(OL
    $(LI Simplifying the process of integration at the build-system level)
    $(LI Removing the need to ensure that Druntime is properly initialized on
    calls to the library, for situations when an initialization step is not
    performed or would be difficult to insert before the library is used.)
    $(LI Mixing memory management strategies (GC + manual memory management) can
    be tricky, hence removing D's GC from the equation may be worthwhile sometimes.)
    )

    $(P BetterC and $(LINK2 https://dlang.org/spec/importc.html, ImportC) are very different.
    ImportC is an actual C compiler. BetterC is a subset of D that relies only on the
    existence of the C Standard library.)


$(H2 $(LNAME2 retained, Retained Features))

    $(P Nearly the full language remains available. Highlights include:)

    $(OL
    $(LI Unrestricted use of compile-time features)
    $(LI Full metaprogramming facilities)
    $(LI Nested functions, nested structs, delegates and $(DDSUBLINK spec/expression, function_literals, lambdas))
    $(LI Member functions, constructors, destructors, operating overloading, etc.)
    $(LI The full module system)
    $(LI Array slicing, and array bounds checking)
    $(LI RAII (yes, it can work without exceptions))
    $(LI `scope(exit)`)
    $(LI Memory safety protections)
    $(LI Interfacing with C++)
    $(LI COM classes and C++ classes)
    $(LI `assert` failures are directed to the C runtime library)
    $(LI `switch` with strings)
    $(LI `final switch`)
    $(LI `unittest`)
    $(LI $(DDSUBLINK spec/interfaceToC, calling_printf, `printf` format validation))
    )

$(H3 $(LNAME2 unittests, Running unittests in `-betterC`))

While, testing can be done without the $(TT -betterC) flag, it is sometimes desirable to run the testsuite in `-betterC` too.
`unittest` blocks can be listed with the $(DDSUBLINK spec/traits, getUnitTests, `getUnitTests`) trait:

---
unittest
{
   assert(0);
}

extern(C) void main()
{
    static foreach(u; __traits(getUnitTests, __traits(parent, main)))
        u();
}
---

$(CONSOLE
$(GT) dmd -betterC -unittest -run test.d
dmd_runpezoXK: foo.d:3: Assertion `0' failed.
)

However, in `-betterC` `assert` expressions don't use Druntime's assert and are directed to `assert` of the C runtime library instead.

$(H2 $(LNAME2 consequences, Unavailable Features))

    $(P D features not available with $(B BetterC):)

$(OL
    $(LI Garbage Collection)
    $(LI TypeInfo and ModuleInfo)
    $(LI Classes)
    $(LI Built-in threading (e.g. $(MREF core, thread)))
    $(LI Dynamic arrays (though slices of static arrays work) and associative arrays)
    $(LI Exceptions)
    $(LI `synchronized` and $(MREF core, sync))
    $(LI Static module constructors or destructors)
)


$(SPEC_SUBNAV_PREV_NEXT simd, Vector Extensions, importc, ImportC)

)

Macros:
    CHAPTER=40
    TITLE=Better C