2d4f3e2ac9
The layer is now redundant, since everything left in "pkgs" is in the "racket-pkgs" category.
83 lines
3.1 KiB
Racket
83 lines
3.1 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual "common.rkt"
|
|
(for-label scheme/base compiler/xform dynext/compile))
|
|
|
|
@(define (xflag str) (as-index (DFlag str)))
|
|
@(define (pxflag str) (as-index (DPFlag str)))
|
|
|
|
@title[#:tag "cc"]{Compiling and Linking C Extensions}
|
|
|
|
A @deftech{dynamic extension} is a shared library (a.k.a. DLL) that
|
|
extends Racket using the C API. An extension can be loaded explicitly
|
|
via @racket[load-extension], or it can be loaded implicitly through
|
|
@racket[require] or @racket[load/use-compiled] in place of a source
|
|
@racket[_file] when the extension is located at
|
|
|
|
@racketblock[
|
|
(build-path "compiled" "native" (system-library-subpath)
|
|
(path-add-suffix _file (system-type 'so-suffix)))
|
|
]
|
|
|
|
relative to @racket[_file].
|
|
|
|
For information on writing extensions, see @other-manual[inside-doc].
|
|
|
|
Three @exec{raco ctool} modes help for building extensions:
|
|
|
|
@itemize[
|
|
|
|
@item{@DFlag{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.}
|
|
|
|
@item{@DFlag{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.}
|
|
|
|
@item{@DFlag{xform} : Transforms C code that is written without
|
|
explicit GC-cooperation hooks to cooperate with Racket's 3m
|
|
garbage collector; see @secref[#:doc inside-doc "overview"] in
|
|
@other-manual[inside-doc].}
|
|
|
|
]
|
|
|
|
Compilation and linking build on the @racketmodname[dynext/compile]
|
|
and @racketmodname[dynext/link] libraries. The following @exec{raco ctool} flags
|
|
correspond to setting or accessing parameters for those libraries: @xflag{tool},
|
|
@xflag{compiler}, @xflag{ccf}, @xflag{ccf}, @xflag{ccf-clear},
|
|
@xflag{ccf-show}, @xflag{linker}, @pxflag{ldf}, @xflag{ldf},
|
|
@xflag{ldf-clear}, @xflag{ldf-show}, @pxflag{ldl}, @xflag{ldl-show},
|
|
@pxflag{cppf}, @pxflag{cppf} @pxflag{cppf-clear}, and @xflag{cppf-show}.
|
|
|
|
The @as-index{@DFlag{3m}} flag specifies that the extension is to be
|
|
loaded into the 3m variant of Racket. The @as-index{@DFlag{cgc}}
|
|
flag specifies that the extension is to be used with the CGC. The
|
|
default depends on @exec{raco}: @DFlag{3m} if @exec{raco} itself is running in
|
|
3m, @DFlag{cgc} if @exec{raco} itself is running in CGC.
|
|
|
|
|
|
@section[#:tag "xform-api"]{API for 3m Transformation}
|
|
|
|
@defmodule[compiler/xform]
|
|
|
|
@defproc[(xform [quiet? any/c]
|
|
[input-file path-string?]
|
|
[output-file path-string?]
|
|
[include-dirs (listof path-string?)]
|
|
[#:keep-lines? keep-lines? boolean? #f])
|
|
any/c]{
|
|
|
|
Transforms C code that is written without explicit GC-cooperation
|
|
hooks to cooperate with Racket's 3m garbage collector; see
|
|
@secref[#:doc '(lib "scribblings/inside/inside.scrbl") "overview"] in
|
|
@other-manual['(lib "scribblings/inside/inside.scrbl")].
|
|
|
|
The arguments are as for @racket[compile-extension]; in addition
|
|
@racket[keep-lines?] can be @racket[#t] to generate GCC-style
|
|
annotations to connect the generated C code with the original source
|
|
locations.
|
|
|
|
The file generated by @racket[xform] can be compiled via
|
|
@racket[compile-extension].}
|
|
|