5 Header Compilation

This library provides facilities for extracting and compiling C header information to generate architecture-specific binary layout information. This is particularly useful for writing code that interacts with the PLT Scheme foreign library—see FFI: Racket Foreign Interface.

Specifically, the foreign library’s pointer-manipulation procedures such as ptr-ref and ptr-set! can be used to read and write to arbitrary addresses, which can be computed using layout information.

(require (planet dherman/c:3:3/header))

5.1 Headers

(header? x) → boolean?

x : any

Determines whether x is a header.

(make-header components) → header?

components : (listof (or/c decl? header?))

Constructs a header.

(header component ...+) → header?

component : (or/c decl? header?)

Constructs a header.

Examples:
> (define example.h
    (make-header (include/reader "example.h"
                                 (make-program-reader))))
> (define time.h
    (header
     (struct tm ([int tm_sec]
                 [int tm_min]
                 [int tm_hour]
                 [int tm_mday]
                 [int tm_mon]
                 [int tm_year]
                 [int tm_wday]
                 [int tm_yday]
                 [int tm_isdst]))))

Using the Scribble @-reader, the latter example could be rewritten with embedded C syntax as:

(define time.h
  (make-header
   @program{
     struct tm {
         int tm_sec;
         int tm_min;
         int tm_hour;
         int tm_mday;
         int tm_mon;
         int tm_year;
         int tm_wday;
         int tm_yday;
         int tm_isdst;
     };
   }))

5.2 Compilation

(compile-header header compiler) → abi?

header : header?

compiler : ((listof query?) -> (listof uint))

Compiles header using the given compiler, producing an ABI. See Application Binary Interfaces (ABI’s).

A header compiler must recognize the following types of queries.

(query? x) → boolean?

x : any

Determines whether x is a query

(struct		query:sizeof (type)
		#:extra-constructor-name make-query:sizeof)

type : any

A query to determine the size of the type represented by type.

(struct		query:offset (type field)
		#:extra-constructor-name make-query:offset)

type : any

field : symbol?

A query to determine the offset of field in type.

(struct		query:expr (expr)
		#:extra-constructor-name make-query:expr)

expr : any

A query to determine the value of the integer expression expr.

(system-compiler	[	#:include<> include<>
		#:include include
		exe])

→ ((listof query?) -> (listof uint))

include<> : (listof string?) = '()

include : (listof string?) = '()

exe : ((-> any) -> any) = gcc

A header compiler that delegates to an external C compiler, presumably installed on the current system. The queries are converted into a series of C statements which are assembled into a C program that produces the answers. The include<> list is used to generate the list of system C headers to be included in the generated C program, and the include list is the list of path strings for local headers included in the generated C program. The gcc compiler is used by default, but this can be overridden by providing an alternative system compiler for the exe argument.