12.1 Compiling and Linking C Extensions

► |  | raco: Racket Command-Line Tools

1 | raco make: Compiling Source to Bytecode
2 | raco exe: Creating Stand-Alone Executables
3 | raco distribute: Sharing Stand-Alone Executables
4 | raco planet: Automatic Package Distribution
5 | raco pkg: Package Management
6 | raco setup: Installation Management
7 | raco decompile: Decompiling Bytecode
8 | raco demod: Demodularizing Programs
9 | raco link: Library Collection Links
10 | raco pack: Packing Library Collections
11 | raco unpack: Unpacking Library Collections
12 | raco ctool: Working with C Code
13 | raco test: Run tests
14 | raco docs: Documentation Search
15 | raco expand: Macro Expansion
16 | raco read: Reading and Pretty-Printing
17 | raco scribble: Building Documentation
18 | Adding a raco Command
19 | Installation Configuration and Search Paths

▼ | 12 | raco ctool: Working with C Code

12.1 | Compiling and Linking C Extensions
12.2 | Embedding Modules via C

► | 12.1 | Compiling and Linking C Extensions

12.1.1 | API for 3m Transformation

On this page:

12.1.1`` API for 3m Transformation
xform

top ← prev up next →

#### 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.

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 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

> > procedure
> > (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

Transforms C code that is written without explicit GC-cooperation hooks to cooperate with Racket’s 3m garbage collector; see Overview in Inside: Racket C API.

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.

top ← prev up next →