12.1 Compiling and Linking C Extensions
A dynamic extension is a shared library (a.k.a. DLL) that extends Racket using the C API. An extension can be loaded explicitly via load-extension, or it can be loaded implicitly through require or load/use-compiled in place of a source file when the extension is located at
(build-path "compiled" "native" (system-library-subpath) (path-add-suffix file (system-type 'so-suffix)))
relative to file.
For information on writing extensions, see Inside: Racket C API.
raco ctool is provided by the "cext-lib" package.
Three raco ctool modes help for building extensions:
--cc : Runs the host system’s C compiler, automatically supplying flags to locate the Racket header files and to compile for inclusion in a shared library.
--ld : Runs the host system’s C linker, automatically supplying flags to locate and link to the Racket libraries and to generate a shared library.
--xform : Transforms C code that is written without explicit GC-cooperation hooks to cooperate with Racket’s 3m garbage collector; see Overview (BC) in Inside: Racket C API.
Compilation and linking build on the dynext/compile and dynext/link libraries. The following raco ctool flags correspond to setting or accessing parameters for those libraries: --tool, --compiler, --ccf, --ccf, --ccf-clear, --ccf-show, --linker, ++ldf, --ldf, --ldf-clear, --ldf-show, ++ldl, --ldl-show, ++cppf, ++cppf ++cppf-clear, and --cppf-show.
The --3m flag specifies that the extension is to be loaded into the 3m variant of Racket. The --cgc flag specifies that the extension is to be used with the CGC. The default depends on raco: --3m if raco itself is running in 3m, --cgc if raco itself is running in CGC.
12.1.1 API for 3m Transformation
|(require compiler/xform)||package: cext-lib|
(xform quiet? input-file output-file include-dirs [ #:keep-lines? keep-lines?]) → any/c quiet? : any/c input-file : path-string? output-file : path-string? include-dirs : (listof path-string?) keep-lines? : boolean? = #f
The arguments are as for compile-extension; in addition keep-lines? can be #t to generate GCC-style annotations to connect the generated C code with the original source locations.
The file generated by xform can be compiled via compile-extension.