{"id":1257,"date":"2017-12-05T15:52:46","date_gmt":"2017-12-05T15:52:46","guid":{"rendered":"http:\/\/dlang.org\/blog\/?p=1257"},"modified":"2021-10-08T11:07:00","modified_gmt":"2021-10-08T11:07:00","slug":"interfacing-d-with-c-getting-started","status":"publish","type":"post","link":"https:\/\/dlang.org\/blog\/2017\/12\/05\/interfacing-d-with-c-getting-started\/","title":{"rendered":"Interfacing D with C: Getting Started"},"content":{"rendered":"

\"\"One of the early design goals behind the D programming language was the ability to interface with C<\/a>. To that end, it provides ABI compatibility, allows access to the C standard library, and makes use of the same object file formats and system linkers that C and C++ compilers use. Most built-in D types, even structs, are directly compatible with their C counterparts and can be passed freely to C functions, provided the functions have been declared in D with the appropriate linkage attribute<\/a>. In many cases, one can copy a chunk of C code, paste it into a D module, and compile it with minimal adjustment. Conversely, appropriately declared D functions can be called from C.<\/p>\n

That\u2019s not to say that D carries with it all of C\u2019s warts. It includes features intended to eliminate, or more easily avoid, some of the errors that are all too easy to make in C. For example, bounds checking of arrays is enabled by default, and a safe subset of the language provides compile-time enforcement of memory safety. D also changes or avoids some things that C got wrong, such as what Walter Bright sees as C\u2019s biggest mistake<\/a>: conflating pointers with arrays. It\u2019s in these differences of implementation that surprises lurk for the uninformed.<\/p>\n

This post is the first in a series exploring the interaction of D and C in an effort to inform the uninformed. I\u2019ve previously written about the basics of this topic in an article at GameDev.net<\/a>, and in my book, \u2018Learning D<\/a>\u2019, where the entirety of Chapter 9 covers it in depth.<\/p>\n

This blog series will focus on those aforementioned corner cases so that it\u2019s not necessary to buy the book or to employ trial and error in order to learn them. As such, I\u2019ll leave the basics to the GameDev.net article and recommend that anyone interfacing D with C (or C++) give it a read along with the official documentation<\/a>.<\/p>\n

The C and D code that I provide to highlight certain behavior is intended to be compiled and linked by the reader. The code demonstrates both error and success conditions. Recognizing and understanding compiler errors is just as important as knowing how to fix them, and seeing them in action can help toward that end. That implies some prerequisite knowledge of compiling and linking C and D source files. Happily, that\u2019s the focus of the next section of this post.<\/p>\n

For the C code, we\u2019ll be using the Digital Mars C\/C++ and Microsoft C\/C++ compilers on Windows, and GCC and Clang elsewhere. On the D side, we\u2019ll be working exclusively with the D reference compiler, DMD. Windows users unfamiliar with setting up DMD to work with the Microsoft tools will be well served by the post on this blog titled, \u2018DMD, Windows, and C<\/a>\u2019.<\/p>\n

We\u2019ll finish the post with a look at one of the corner cases, one that is likely to rear its head early on in any exploration of interfacing D with C, particularly when creating bindings to existing C libraries.<\/p>\n

Compiling and linking<\/h3>\n

The articles in this series will present example C source code that is intended to be saved and compiled into object files for linking with D programs. The command lines for generating the object files look pretty much the same on every platform, with a couple of caveats. We\u2019ll look first at Windows, then lump all the other supported systems together in a single section.<\/p>\n

In the next two sections, we\u2019ll be working with the following C and D source files. Save them in the same directory (for convenience) and make sure to keep the names distinct. If both files have the same name in the same directory, then the object files created by the C compiler and DMD will also have the same name, causing the latter to overwrite the former. There are compiler switches to get around this, but for a tutorial we\u2019re better off keeping the command lines simple.<\/p>\n

chello.c<\/strong><\/p>\n

#include <stdio.h>\r\nvoid say_hello(void) \r\n{\r\n    puts(\"Hello from C!\");\r\n}<\/pre>\n
hello.d<\/strong><\/p>\n
extern(C) void say_hello();\r\nvoid main() \r\n{\r\n    say_hello();\r\n}<\/pre>\n
The extern(C)<\/code> bit in the declaration of the C function in the D code is a linkage attribute<\/a>. That’s covered by the other material I referenced above, but it’s a potential gotcha we’ll look at later in this series.<\/p>\n
Windows<\/h4>\n
The official DMD packages for Windows, available at dlang.org<\/a> as a zip archive and an installer, are the only released versions of DMD that do not require any additional tooling to be installed as a prerequisite to compile D files. These packages ship with everything they need to compile 32-bit executables in the OMF format (again, I refer you to \u2018DMD, Windows, and C<\/a>\u2019 for the details).<\/p>\n
When linking any foreign object files with a D program, it\u2019s important that the object file format and architecture match the D compiler output. The former is an issue primarily on Windows, while attention must be paid to the latter on all platforms.<\/p>\n
Compiling C source to a format compatible with vanilla DMD on Windows requires the Digital Mars C\/C++ compiler<\/a>. It\u2019s a free download and ships with some of the same tools as DMD. It outputs object files in the OMF format. With both it and DMD installed and on the system path, the above source files can be compiled, linked, and executed like so:<\/p>\n
dmc -c chello.c\r\ndmd hello.d chello.obj\r\nhello<\/pre>\n
The -c<\/code> option tells DMC to forego linking, causing it to only compile the C source and write out the object file chello.obj<\/code>.<\/p>\n
To get 64-bit output on Windows, DMC is not an option. In that case, DMD requires the Microsoft build tools on Windows. Once the MS build tools are installed and set up, open the preconfigured x64 Native Tools Command Prompt from the Start menu and execute the following commands (again, see \u2018D, Windows, and C<\/a>\u2019 on this blog for information on how to get the Microsoft build tools and open the preconfigured command prompt, which may have a slightly different name depending on the version of Visual Studio or the MS Build Tools installed):<\/p>\n
cl \/c chello.c\r\ndmd -m64 hello.d chello.obj\r\nhello<\/pre>\n
Again, the \/c<\/code> option tells the compiler not to link. To produce 32-bit output with the MS compiler, open a preconfigured x86 Native Tools Command Prompt and execute these commands:<\/p>\n
cl \/c hello.c\r\ndmd -m32mscoff hello.c chello.obj\r\nhello<\/pre>\n
DMD recognizes the -m32<\/code> switch on Windows, but that tells it to produce 32-bit OMF output (the default), which is not compatible with Microsoft\u2019s linker, so we must use -m32mscoff<\/code> here instead.<\/p>\n
Other platforms<\/h4>\n
On the other platforms D supports, the system C compiler is likely going to be GCC or Clang, one of which you will already have installed if you have a functioning dmd<\/code> command. On Mac OS, clang<\/code> can be installed via XCode<\/code> in the App Store. Most Linux and BSD systems have a GCC package available, such as via the often recommended command line, apt-get install build-essential<\/code>, on Debian and Debian-based systems. Please see the documentation for your system for details.<\/p>\n
On these systems, the environment variable CC<\/code> is often set to the system compiler command. Feel free to substitute either gcc<\/code> or clang<\/code> for CC<\/code> in the lines below as appropriate for your system.<\/p>\n
CC -c chello.c\r\ndmd hello.d chello.o\r\n.\/hello<\/pre>\n
This will produce either 32-bit or 64-bit output, depending on your system configuration. If you are on a 64-bit system and have 32-bit developer tools installed, you can pass -m32<\/code> to both CC<\/code> and dmd<\/code> to generate 32-bit binaries.<\/p>\n
The long<\/code> way<\/h3>\n
Now that we\u2019re configured to compile and link C and D source in the same binary, let\u2019s take a look at a rather common gotcha. To fully appreciate this one, it helps to compile it on both Windows and another platform.<\/p>\n
One of the features of D is that all of the integral types have a fixed size. A short<\/code> is always 2 bytes and an int<\/code> is always 4. This never changes, no matter the underlying system architecture. This is quite different from C, where the spec only imposes relative requirements on the size of each integral type and leaves the specifics to the implementation. Even so, there are wide areas of agreement across modern compilers such that on every platform D currently supports the sizes for almost all the integral types match those in D. The exceptions are long<\/code> and ulong<\/code>.<\/p>\n
In D, long<\/code> and ulong<\/code> are always 8 bytes across all platforms. This never changes. It lines up with the corresponding C types just fine on most 64-bit systems under the version(Posix)<\/code> umbrella, where the C\u00a0long<\/code> and unsigned long<\/code> are also 8 bytes. However, they are 4 bytes on 32-bit architectures. Moreover, they\u2019re always<\/em> 4 bytes on Windows, even on a 64-bit architecture.<\/p>\n
Most C code these days will account for these differences either by using the preprocessor to define custom integral types or by making use of the C99 stdint.h<\/code> where types such as int32_t<\/code> and int64_t<\/code> are unambiguously defined. Yet, it\u2019s still possible to encounter C libraries using long<\/code> in the wild.<\/p>\n
Consider the following C function:<\/p>\n
maxval.c<\/strong><\/p>\n
#include <limits.h>\r\nunsigned long max_val(void)\r\n{\r\n    return ULONG_MAX;\r\n}<\/pre>\n
The naive D implementation looks like this:<\/p>\n
showmax1.d<\/strong><\/p>\n
extern(C) ulong max_val();\r\nvoid main()\r\n{\r\n    import std.stdio : writeln;\r\n    writeln(max_val());\r\n}<\/pre>\n
What this does depends on the C compiler and architecture. For example, on Windows with dmc<\/code> I get 7316910580432895<\/code>, with x86\u00a0cl<\/code>\u00a0I get\u00a059663353508790271<\/code>, and\u00a04294967295<\/code> with x64 cl<\/code>. The last one is actually the correct value, even though the size of the unsigned long<\/code>\u00a0on the C side is still 4 bytes as it is in the other two scenarios. I assume this is because the x64 ABI stores return values in the 8-byte RAX<\/code> register, so it can be read into the 8-byte ulong<\/code>\u00a0on the D side with no corruption. The important point here is that the two values in the x86 code are garbage because the D side is expecting a 64-bit return value from 32-bit registers, so it’s reading more than it’s being given.<\/p>\n
Thankfully, DRuntime provides a way around this in core.c.config<\/code>, where you\u2019ll find c_long<\/code> and c_ulong<\/code>. Both of these are conditionally configured to match the compile-time C runtime implementation and architecture configuration. With this, all that\u2019s needed is to change the declaration of max_val<\/code> in the D module, like so:<\/p>\n
showmax2.d<\/strong><\/p>\n
import core.stdc.config : c_ulong;\r\nextern(C) c_ulong max_val();\r\n\r\nvoid main()\r\n{\r\n    import std.stdio : writeln;\r\n    writeln(max_val());\r\n}<\/pre>\n
Compile and run with this\u00a0and you\u2019ll find it does the right thing everywhere. On Windows, it’s\u00a04294967295<\/code>\u00a0across the board.<\/p>\n
Though less commonly encountered, core.stdc.config<\/code> also declares a portable c_long_double<\/code> type to match any long double<\/code> that might pop up in a C library to which a D module must bind.<\/p>\n
Looking ahead<\/h3>\n
In this post, we\u2019ve gotten set up to compile and link C and D in the same executable and have looked at the first of several potential problem spots. We used DMD here, but it should be possible to substitute one of the other D compilers (ldc<\/code>\u00a0or gdc<\/code>) without changing the command line (with the exception of -m32mscoff<\/code>, which is specific to DMD). The next post in this series will focus entirely on getting D arrays and C arrays to cooperate. See you there!<\/p>\n","protected":false},"excerpt":{"rendered":"
One of the early design goals behind the D programming language was the ability to interface with C. To that end, it provides ABI compatibility, allows access to the C standard library, and makes use of the same object file formats and system linkers that C and C++ compilers use. Most built-in D types, even structs, are directly compatible with their C counterparts and can be passed freely to C functions, provided the functions have been declared in D with the appropriate linkage attribute. In many cases, one can copy a chunk of C code, paste it into a D module, and compile it with minimal adjustment. Conversely, appropriately declared D functions can be called from C.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[26,29,30],"tags":[],"_links":{"self":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts\/1257"}],"collection":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/comments?post=1257"}],"version-history":[{"count":20,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts\/1257\/revisions"}],"predecessor-version":[{"id":1367,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts\/1257\/revisions\/1367"}],"wp:attachment":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/media?parent=1257"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/categories?post=1257"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/tags?post=1257"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}