Dynamic FFI🔗 i

1Warning: Read this Section Before Use🔗 i

Like Racket’s built-in ffi/unsafe module, this library allows Racket to use C functions and data structures that are not memory-managed by Racket. Racket cannot provide safety guarantees by default for FFI objects created using this library. Users of this library will be required to self-enforce memory management in C and/or manually expose FFI objects to Racket’s garbage collector. Extra care should be taken to ensure that C functions bound via this library or Racket’s built-in FFI do not contain errors like buffer overflows, which could corrupt the runtime, cause undefined behavior, and prevent Racket from providing useful error messages.

Users of this library should be extremely cautious. The library makes it easier to call C functions from Racket, but does not make it safer.

Finally:

Passing unsanitized user-input to any function in this library is horribly dangerous. You should never do it under any circumstance.

2Dependencies🔗 i

Dynamic FFI requires clang and llvm headers and libraries to work. Clang versions 6 and 7 are both known to work with Dynamic FFI. This library does not bundle clang or llvm.

To install a clang toolchain on Fedora:

sudodnfinstall"@developmenttools"racketllvm-develclang-devel

To install a clang toolchain on Ubuntu:

sudoapt-getinstall"build-essential"racketllvm-devlibclang-devclang

To install a clang toolchain on macOS (assuming that Homebrew is installed), run brewinstallllvm, then follow the instructions emitted by Homebrew to setup paths.

During the raco package install, Dynamic FFI will compile itself and link with the system clang libraries. Dependencies should be installed before the raco installation, or else the library will defer building itself, and will complain about missing dependencies when you try to use it. To finish the installation process, install the required dependencies and run the following command:

racosetup-p-Ddynamic-ffi

3Defining FFIs🔗 i

lib can be a relative library created using dynamic-ffi-lib , or a hard-coded path omitting the object file extension.

(require dynamic-ffi/unsafe)

(define-dynamic-ffi libc

(dynamic-ffi-lib "libc""6")

"/usr/include/stdio.h")

(libc'printf"hello world\n")

4Generating Static FFIs🔗 i

This library has the ability to generate static FFI files that can be used without the dependency on dynamic-ffi.

5Inline FFIs🔗 i

This library allows users to write C functions inline, which will be compiled at runtime and provided as a dynamic FFI.

@define-inline-ffi [mylib]{

intadd(intx,inty){

returnx+y;

}

}

(mylib' add34)

The form can be used without the at-reader as well.

(define-inline-ffi mylib

"int add(int x, int y) {\n"

"return x + y;\n"

"}")

(mylib'add34)

Extra compile flags can be passed to define-inline-ffi , and the default compiler can be overridden.

(define-inline-ffi libm#:compile-flags"-lm"#:compiler"clang"

"#include <math.h>\n"

"double square_root(double x) {\n"

"return sqrt(x);\n"

"}")

(libm'square_root16)

6Limitations🔗 i

This library is able to generate dynamic FFI bindings for a fairly large portion of the C language standard. Occasionally we find special declaration types that clang treats differently, which the library may not have support for yet. When such declarations are encountered, dynamic-ffi will emit error messages with details about the missing functionality. Please report any issues you find at the project issue tracker.

As a workaround in almost every case, define-inline-ffi can be used to write a wrapper around functions that dynamic-ffi is unable to parse.

7Acknowledgements🔗 i

Special thanks to Jay McCarthy for suggesting this project idea, and for his advisership during its implementation.