5.22 Declaring Foreign Libraries Needed at Run Time

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives
5.22 | Declaring Foreign Libraries Needed at Run Time

On this page:

define-runtime-lib

Racket
top contents ← prev up next →

### 5.22 Declaring Foreign Libraries Needed at Run Time🔗ℹ

(require ffi/unsafe/runtime-lib) | package: base

The ffi/unsafe/runtime-lib library is similar to racket/runtime-path (and builds on it), but provides more support for platform-specific choices of libraries.

Added in version 9.2.0.6 of package base.

> > syntax
> > (define-runtime-lib id
> > maybe-ffi-lib-args
> > [platform-spec lib-spec ...]
> > ...
> > [else else-body ...+])
> platform-spec |  | = |  | os-id
> |  | | |  | os*-id
> |  | | |  | arch-id
> |  | | |  | platform-string
> |  | | |  | 32
> |  | | |  | 64
> |  | | |  | (or platform-spec ...)
> |  | | |  | (and platform-spec ...)
> lib-spec |  | = |  | (so lib-string)
> |  | | |  | (so lib-string (vers ...))
> vers |  | = |  | string
> |  | | |  | #f
> maybe-ffi-lib-args |  | = |  |
> |  | | |  | #:ffi-lib-args (arg ...)

Similar to define-runtime-path, but binds id to a result from ffi-lib for a platform that matches one of the platform-specs (which are tried in order), or to the result of the else-body sequence otherwise.

A platform-spec implies a set of libraries that are loaded in order as enumerated by the accompanying lib-specs, where the lib-string within a lib-spec becomes the first argument to ffi-lib, and the vers sequence (if present) is quoted as the second argument. The defined id is bound to a ffi-lib result for the last lib-spec, or to #f if no lib-specs are present in the matching clause. Besides loading the library for each lib-spec at run time, the libraries are declared at compile time for use by tools such as raco exe and raco dist. Cross compilation is handled automatically, so that the target platforms libraries are listed at compile time, while run time loads libraries suitable to the host platform.

If no platform-spec matches, then id is bound to the result of the else-body sequence—which does not have to be a result from ffi-lib, but typically it is. The else-body sequence is evaluated only at run-time, and no libraries are declared at compile time.

Each platform-spec is is compared to the result of (system-type 'os), (system-type 'os*), (system-type 'arch), (system-type 'platform), and/or (system-type 'word). In an and form, all platform-specs much match, while only one matching platform-spec is needed ro an or form.

Extra keyword arguments can be supplied the run-time ffi-lib call for a platform-spec match through an optional #:ffi-lib-args declaration. There’s a single #:ffi-lib-args declaration, because it needs to be independent of the platform-spec that turns out to match. The run-time call receives either an absolute path based on resolved lib-spec, or it receives just the initial lib-string within a lib-spec (due to limitations of define-runtime-path), so #:fail is the most likely useful extra argument to ffi-lib.

top contents ← prev up next →