Retropikzel
/
foreign-c
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improving documentation

This commit is contained in:
retropikzel 2025-03-12 15:52:31 +02:00
parent 1ba179d7cd
commit fe7822cb29
6 changed files with 1115 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Makefile
View File

@ -1,10 +1,23 @@
.PHONY=libtest.o libtest.so libtest.a .PHONY=libtest.o libtest.so libtest.a documentation
CC=gcc CC=gcc
DOCKER=docker run -it -v ${PWD}:/workdir DOCKER=docker run -it -v ${PWD}:/workdir
DOCKER_INIT=cd /workdir && make clean && DOCKER_INIT=cd /workdir && make clean &&
all: chibi gauche libtest.so libtest.o libtest.a all: chibi gauche libtest.so libtest.o libtest.a
# apt-get install pandoc weasyprint
docs:
mkdir -p documentation
pandoc --standalone \
--template templates/documentation.html README.md \
> documentation/R7RS-PFFI.html
#pandoc -s --pdf-engine=weasyprint -o documentation/R7RS-PFFI.pdf README.md
pandoc -t html5 \
--pdf-engine=weasyprint \
--css templates/css/pdf-documentation.css \
-o documentation/R7RS-PFFI.pdf \
README.md
chibi: chibi:
chibi-ffi src/chibi/pffi.stub chibi-ffi src/chibi/pffi.stub
${CC} -g3 -o retropikzel/pffi/chibi-pffi.so \ ${CC} -g3 -o retropikzel/pffi/chibi-pffi.so \
@ -46,7 +59,8 @@ test-compile-library: libtest.so libtest.a libtest.o
SCHEME=${SCHEME} compile-r7rs-library retropikzel/pffi.sld SCHEME=${SCHEME} compile-r7rs-library retropikzel/pffi.sld
test-compile: test-compile-library test-compile: test-compile-library
SCHEME=${SCHEME} CFLAGS="-I./include" LDFLAGS="-ltest" compile-r7rs -I . test.scm && ./test SCHEME=${SCHEME} CFLAGS="-I./include -L." LDFLAGS="-ltest libtest.o" compile-r7rs -I . test.scm
./test
test-compile-docker: libtest.so libtest.a test-compile-docker: libtest.so libtest.a
docker build -f dockerfiles/test . --build-arg SCHEME=${SCHEME} --tag=pffi-${SCHEME} docker build -f dockerfiles/test . --build-arg SCHEME=${SCHEME} --tag=pffi-${SCHEME}

136
README.md
View File

@ -1,8 +1,12 @@
# Portable Foreign Function Interface for R7RS schemes ---
title: Portable Foreign Function Interface for R7RS Documentation
---
Foreign function interface that is supported on multiple R7RS Sceheme implementations. # Portable Foreign Function Interface for R7RS
Any help in form of constructive advice and bug reports are appreciated. Portable foreign function interface for R7RS. It is portable in the sense that
it supports multiple implementations, as opposed to being portable by
conforming to some specification.
[Project](https://todo.sr.ht/~retropikzel/r7rs-pffi) [Project](https://todo.sr.ht/~retropikzel/r7rs-pffi)
@ -14,44 +18,55 @@ Any help in form of constructive advice and bug reports are appreciated.
## Table of contents ## Table of contents
<nav>
- [Goals](#goals) - [Goals](#goals)
- [Non Goals](#non-goals) - [Non Goals](#non-goals)
- [Status](#status) - [Status](#status)
- [Implementation status](#implementation-status) - [Current caveats](#current-caveats)
- [Implementation table](#implementation-table) - [Implementation table](#implementation-table)
- [Other Implementations](#other-implementations) - [Beta](#beta)
- [Alpha](#alpha)
- [Not started](#not-started)
- [Other](#other)
- [Documentation](#documentation) - [Documentation](#documentation)
- [Usage](#usage) - [Usage](#usage)
- [Chibi](#usage_chibi) - [Chibi](#usage-chibi)
- [Chicken](#usage_chicken) - [Chicken](#usage-chicken)
- [Racket](#usage_racket) - [Racket](#usage-racket)
- [Kawa](#usage_kawa) - [Kawa](#usage-kawa)
- [Reference](#reference) - [Reference](#reference)
- [Types](#types) - [Types](#types)
- [Procedures and macros](#procedures-and-macros) - [Procedures and macros](#procedures-and-macros)
- [pffi-init](#strongpffi-initstrong) - [pffi-init](#pffi-init)
- [pffi-size-of](#strongpffi-size-ofstrong-type--gt-number) - [pffi-size-of](#pffi-size-of)
- [pffi-align-of](#strongpffi-align-ofstrong-type--gt-number) - [pffi-align-of](#pffi-align-of)
- [pffi-shared-object-auto-load](#strongpffi-shared-object-auto-loadstrong) - [pffi-shared-object-auto-load](#pffi-shared-object-auto-load)
- [pffi-shared-object-load](#strongpffi-shared-object-loadstrong-headers-path) - [pffi-shared-object-load](#pffi-shared-object-load)
- [pffi-pointer-null](#strongpffi-pointer-nullstrong--gt-pointer) - [pffi-pointer-null](#pffi-pointer-null)
- [pffi-pointer-null?](#strongpffi-pointer-nullstrong-pointer--gt-boolean) - [pffi-pointer-null?](#pffi-pointer-null?)
- [pffi-pointer-allocate](#strongpffi-pointer-allocatestrong-size--gt-pointer) - [pffi-pointer-allocate](#pffi-pointer-allocate)
- [pffi-pointer?](#strongpffi-pointerstrong-object--gt-boolean) - [pffi-pointer-address](#pffi-pointer-address)
- [pffi-pointer-free](#strongpffi-pointer-freestrong-pointer) - [pffi-pointer?](#pffi-pointer?)
- [pffi-pointer-set!](#strongpffi-pointer-setstrong-pointer-type-offset-value) - [pffi-pointer-free](#pffi-pointer-free)
- [pffi-pointer-get](#strongpffi-pointer-getstrong-pointer-type-offset--gt-object) - [pffi-pointer-set!](#pffi-pointer-set!)
- [pffi-string->pointer](#strongpffi-string-gtpointerstrong-string--gt-pointer) - [pffi-pointer-get](#pffi-pointer-get)
- [pffi-pointer->string](#strongpffi-pointer-gtstringstrong-pointer--gt-string) - [pffi-string->pointer](#pffi-string-to-pointer)
- [pffi-struct-make](#strongpffi-struct-makestrong-name-members--pointer--gt-pffi-struct) - [pffi-pointer->string](#pffi-pointer-to-string)
- [pffi-struct-pointer](#strongpffi-struct-pointerstrong-pffi-struct--gt-pointer) - [pffi-struct-make](#pffi-struct-make)
- [pffi-struct-offset-get](#strongpffi-struct-offset-getstrong-member-name--gt-number) - [pffi-struct-pointer](#pffi-struct-pointer)
- [pffi-struct-get](#strongpffi-struct-getstrong-pffi-struct-member-name--gt-object) - [pffi-struct-offset-get](#pffi-struct-offset-get)
- [pffi-struct-set!](#strongpffi-struct-setstrong-pffi-struct-member-name-value) - [pffi-struct-get](#pffi-struct-get)
- [pffi-define](#strongpffi-definestrong-scheme-name-shared-object-c-name-return-type-argument-types) - [pffi-struct-set!](#pffi-struct-set!)
- [pffi-define-callback](#strongpffi-define-callbackstrong-scheme-name-return-type-argument-types-procedure) - [pffi-define](#pffi-define)
- [pffi-define-callback](#pffi-define-callback)
</nav>
<main>
## Goals ## Goals
<a name="goals"></a>
- Support only R7RS implementations - Support only R7RS implementations
- Same interface on all implementations - Same interface on all implementations
@ -60,6 +75,7 @@ Any help in form of constructive advice and bug reports are appreciated.
- Stability and being boring after 1.0.0 is reached - Stability and being boring after 1.0.0 is reached
## Non goals ## Non goals
<a name="non-goals"></a>
- To have every possible FFI feature - To have every possible FFI feature
- Compiling of used library C code at any point - Compiling of used library C code at any point
@ -67,6 +83,7 @@ Any help in form of constructive advice and bug reports are appreciated.
- The pffi library itself may require compilation on installation - The pffi library itself may require compilation on installation
## Status ## Status
<a name="status"></a>
Currently the interface of the library is in okay shape. It propably will not change much but no Currently the interface of the library is in okay shape. It propably will not change much but no
guarantees are being made just yet. guarantees are being made just yet.
@ -76,16 +93,20 @@ different stage. As a whole it is still in **alpha** stage. That said the interf
changing anymore and some implementations are in **beta**. changing anymore and some implementations are in **beta**.
### Current caveats ### Current caveats
<a name="current-caveats"></a>
- No way to pass structs by value - No way to pass structs by value
- Most implementations are missing callback support - Most implementations are missing callback support
## Implementation table ## Implementation table
<a name="implementation-table"></a>
### Beta ### Beta
<a name="beta"></a>
| | pffi-init | pffi-size-of | pffi-shared-object-auto-load | pffi-shared-object-load | pffi-pointer-null | pffi-pointer-null? | pffi-pointer-allocate | pffi-pointer-address | pffi-pointer? | pffi-pointer-free | pffi-pointer-set! | pffi-pointer-get | pffi-string->pointer | pffi-pointer->string | pffi-struct-make | pffi-struct-pointer | pffi-struct-offset-get | pffi-struct-get | pffi-struct-set! | pffi-define | pffi-define-callback | | | pffi-init | pffi-size-of | pffi-shared-object-auto-load | pffi-shared-object-load | pffi-pointer-null | pffi-pointer-null? | pffi-pointer-allocate | pffi-pointer-address | pffi-pointer? | pffi-pointer-free | pffi-pointer-set! | pffi-pointer-get | pffi-string->pointer | pffi-pointer->string | pffi-struct-make | pffi-struct-pointer | pffi-struct-offset-get | pffi-struct-get | pffi-struct-set! | pffi-define | pffi-define-callback |
|--------------|-----------|--------------|------------------------------|-------------------------|-------------------|--------------------|-----------------------|----------------------|---------------|-------------------|-------------------|------------------|----------------------|----------------------|------------------|---------------------|------------------------|-----------------|------------------|-------------|----------------------| |--------------|:---------:|:------------:|:----------------------------:|:-----------------------:|:-----------------:|:------------------:|:---------------------:|:--------------------:|:-------------:|:-----------------:|:-----------------:|:----------------:|:--------------------:|:--------------------:|:----------------:|:-------------------:|:----------------------:|:---------------:|:----------------:|:-----------:|:--------------------:|
| Chibi | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | | | Chibi | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | X | |
| Gauche | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | | | Gauche | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | |
| Guile | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X | | Guile | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X |
@ -93,10 +114,12 @@ changing anymore and some implementations are in **beta**.
| Racket | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X | | Racket | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X |
| Saggittarius | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X | | Saggittarius | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X |
### Alpha ### Alpha
<a name="alpha"></a>
| | pffi-init | pffi-size-of | pffi-shared-object-auto-load | pffi-shared-object-load | pffi-pointer-null | pffi-pointer-null? | pffi-pointer-allocate | pffi-pointer-address | pffi-pointer? | pffi-pointer-free | pffi-pointer-set! | pffi-pointer-get | pffi-string->pointer | pffi-pointer->string | pffi-struct-make | pffi-struct-pointer | pffi-struct-offset-get | pffi-struct-get | pffi-struct-set! | pffi-define | pffi-define-callback | | | pffi-init | pffi-size-of | pffi-shared-object-auto-load | pffi-shared-object-load | pffi-pointer-null | pffi-pointer-null? | pffi-pointer-allocate | pffi-pointer-address | pffi-pointer? | pffi-pointer-free | pffi-pointer-set! | pffi-pointer-get | pffi-string->pointer | pffi-pointer->string | pffi-struct-make | pffi-struct-pointer | pffi-struct-offset-get | pffi-struct-get | pffi-struct-set! | pffi-define | pffi-define-callback |
|--------------|-----------|--------------|------------------------------|-------------------------|-------------------|--------------------|-----------------------|----------------------|---------------|-------------------|-------------------|------------------|----------------------|----------------------|------------------|---------------------|------------------------|-----------------|------------------|-------------|----------------------| |--------------|:---------:|:------------:|:----------------------------:|:-----------------------:|:-----------------:|:------------------:|:---------------------:|:--------------------:|:-------------:|:-----------------:|:-----------------:|:----------------:|:--------------------:|:--------------------:|:----------------:|:-------------------:|:----------------------:|:---------------:|:----------------:|:-----------:|:--------------------:|
| Chicken-5 | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X | | Chicken-5 | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | X |
| Cyclone | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | | | Cyclone | X | X | X | X | X | X | X | | X | X | X | X | X | X | X | X | X | X | X | X | |
| Gambit | X | X | | | | | | X | | | | | | | X | X | X | X | X | | | | Gambit | X | X | | | | | | X | | | | | | | X | X | X | X | X | | |
@ -109,6 +132,7 @@ changing anymore and some implementations are in **beta**.
| Ypsilon | | | | | | | | | | | | | | | X | X | X | X | X | | | | Ypsilon | | | | | | | | | | | | | | | X | X | X | X | X | | |
### Not started ### Not started
<a name="not-started"></a>
- [LIPS](https://lips.js.org/) - [LIPS](https://lips.js.org/)
- Will work on nodejs by using some C FFI library from npm - Will work on nodejs by using some C FFI library from npm
@ -130,6 +154,7 @@ changing anymore and some implementations are in **beta**.
- Need to study the implementation more - Need to study the implementation more
### Other ### Other
<a name="other"></a>
- [s7](https://scheme.fail://ccrma.stanford.edu/software/snd/snd/s7.html) - [s7](https://scheme.fail://ccrma.stanford.edu/software/snd/snd/s7.html)
- Propably does not need FFI as it is embeddable only - Propably does not need FFI as it is embeddable only
@ -137,10 +162,13 @@ changing anymore and some implementations are in **beta**.
- Desires no C interop, I can respect that - Desires no C interop, I can respect that
## Documentation ## Documentation
<a name="documentation"></a>
### Usage <a name="#usage"></a> ### Usage
<a name="usage"></a>
#### Chibi <a name="#usage_chibi"></a> #### Chibi
<a name="usage-chibi"></a>
Needs libffi-dev, on Debina/Ubuntu/Mint install with: Needs libffi-dev, on Debina/Ubuntu/Mint install with:
@ -151,19 +179,22 @@ Build with:
chibi-ffi retropikzel/r7rs-pffi/r7rs-pffi-chibi.stub chibi-ffi retropikzel/r7rs-pffi/r7rs-pffi-chibi.stub
gcc -o retropikzel/r7rs-pffi/r7rs-pffi-chibi.so -fPIC -shared retropikzel/r7rs-pffi/r7rs-pffi-chibi.c -lchibi-scheme -lffi gcc -o retropikzel/r7rs-pffi/r7rs-pffi-chibi.so -fPIC -shared retropikzel/r7rs-pffi/r7rs-pffi-chibi.c -lchibi-scheme -lffi
#### Chicken <a name="#usage_chicken"></a> #### Chicken
<a name="usage-chicken"></a>
Needs [r7rs egg](https://wiki.call-cc.org/eggref/5/r7rs), install with: Needs [r7rs egg](https://wiki.call-cc.org/eggref/5/r7rs), install with:
chicken-install r7rs chicken-install r7rs
#### Racket <a name="#usage_racker"></a> #### Racket
<a name="usage-racket"></a>
Needs [racket-r7rs](https://github.com/lexi-lambda/racket-r7rs), install with: Needs [racket-r7rs](https://github.com/lexi-lambda/racket-r7rs), install with:
raco pkg install --auto r7rs raco pkg install --auto r7rs
#### Kawa <a name="#usage_kawa"></a> #### Kawa
<a name="usage-kawa"></a>
Kawa Needs at least Java version 22 Kawa Needs at least Java version 22
@ -175,8 +206,10 @@ Needs jvm flags:
- --enable-native-access=ALL-UNNAMED - --enable-native-access=ALL-UNNAMED
### Reference ### Reference
<a name="reference"></a>
#### Types #### Types
<a name="types"></a>
Types are given as symbols, for example 'int8 or 'pointer. Types are given as symbols, for example 'int8 or 'pointer.
@ -203,23 +236,28 @@ Types are given as symbols, for example 'int8 or 'pointer.
- Callback function - Callback function
#### Procedures and macros #### Procedures and macros
<a name="procedures-and-macros"></a>
Some of these are procedures and some macros, it might also change implementation to implementation. Some of these are procedures and some macros, it might also change implementation to implementation.
##### **pffi-init** ##### **pffi-init**
<a name="pffi-init"></a>
Always call this first, on most implementation it does nothing but some implementations might need Always call this first, on most implementation it does nothing but some implementations might need
initialisation run. initialisation run.
##### **pffi-size-of** object -> number ##### **pffi-size-of** object -> number
<a name="pffi-size-of"></a>
Returns the size of the pffi-struct, pffi-enum or pffi-type. Returns the size of the pffi-struct, pffi-enum or pffi-type.
##### **pffi-align-of** type -> number ##### **pffi-align-of** type -> number
<a name="pffi-align-of"></a>
Returns the align of the type. Returns the align of the type.
##### **pffi-shared-object-auto-load** headers shared-object-name [options] -> object ##### **pffi-shared-object-auto-load** headers shared-object-name [options] -> object
<a name="pffi-shared-object-auto-load"></a>
Load given shared object automatically searching many predefined paths. Load given shared object automatically searching many predefined paths.
@ -249,6 +287,7 @@ Example:
##### **pffi-shared-object-load** headers path [options] ##### **pffi-shared-object-load** headers path [options]
<a name="pffi-shared-object-load"></a>
It is recommended to use the pffi-shared-object-auto-load instead of this It is recommended to use the pffi-shared-object-auto-load instead of this
directly. directly.
@ -268,26 +307,37 @@ Options:
- List of different versions of library to try, for example (list ".0" ".1") - List of different versions of library to try, for example (list ".0" ".1")
##### **pffi-pointer-null** -> pointer ##### **pffi-pointer-null** -> pointer
<a name="pffi-pointer-null"></a>
Returns a new NULL pointer. Returns a new NULL pointer.
##### **pffi-pointer-null?** pointer -> boolean ##### **pffi-pointer-null?** pointer -> boolean
<a name="pffi-pointer-null?"></a>
Returns #t if given pointer is null pointer, #f otherwise. Returns #t if given pointer is null pointer, #f otherwise.
##### **pffi-pointer-allocate** size -> pointer ##### **pffi-pointer-allocate** size -> pointer
<a name="pffi-pointer-allocate"></a>
Returns newly allocated pointer of given size. Returns newly allocated pointer of given size.
##### **pffi-pointer-address** pointer -> number
<a name="pffi-pointer-address"></a>
Returns the address of given pointer as number.
##### **pffi-pointer?** object -> boolean ##### **pffi-pointer?** object -> boolean
<a name="pffi-pointer?"></a>
Returns #t if given object is pointer, #f otherwise. Returns #t if given object is pointer, #f otherwise.
##### **pffi-pointer-free** pointer ##### **pffi-pointer-free** pointer
<a name="pffi-pointer-free"></a>
Frees given pointer. Frees given pointer.
##### **pffi-pointer-set!** pointer type offset value ##### **pffi-pointer-set!** pointer type offset value
<a name="pffi-pointer-set!"></a>
Sets the value on a pointer on given offset. For example: Sets the value on a pointer on given offset. For example:
@ -297,6 +347,7 @@ Sets the value on a pointer on given offset. For example:
Would set the offset of 64, on pointer p to value 100. Would set the offset of 64, on pointer p to value 100.
##### **pffi-pointer-get** pointer type offset -> object ##### **pffi-pointer-get** pointer type offset -> object
<a name="pffi-pointer-get"></a>
Gets the value from a pointer on given offset. For example: Gets the value from a pointer on given offset. For example:
@ -306,14 +357,17 @@ Gets the value from a pointer on given offset. For example:
> 100 > 100
##### **pffi-string->pointer** string -> pointer ##### **pffi-string->pointer** string -> pointer
<a name="pffi-string-to-pointer"></a>
Makes pointer out of a given string. Makes pointer out of a given string.
##### **pffi-pointer->string** pointer -> string ##### **pffi-pointer->string** pointer -> string
<a name="pffi-pointer-to-string"></a>
Makes string out of a given pointer. Makes string out of a given pointer.
##### **pffi-struct-make** c-type members . pointer -> pffi-struct ##### **pffi-struct-make** c-type members . pointer -> pffi-struct
<a name="pffi-struct-make"></a>
Creates a new pffi-struct and allocates pointer for it. The members argument is a list of member Creates a new pffi-struct and allocates pointer for it. The members argument is a list of member
names and types. For example: names and types. For example:
@ -324,6 +378,7 @@ names and types. For example:
C-type argument can be symbol or a string. C-type argument can be symbol or a string.
##### **pffi-struct-pointer** pffi-struct -> pointer ##### **pffi-struct-pointer** pffi-struct -> pointer
<a name="pffi-struct-pointer"></a>
Returns the pointer that holds the struct content. You need to use this when passing a struct as Returns the pointer that holds the struct content. You need to use this when passing a struct as
a pointer to foreign functions. a pointer to foreign functions.
@ -332,19 +387,23 @@ a pointer to foreign functions.
(pffi-struct-pointer s) (pffi-struct-pointer s)
##### **pffi-struct-offset-get** member-name -> number ##### **pffi-struct-offset-get** member-name -> number
<a name="pffi-struct-offset-get"></a>
Returns the offset of a struct member with given name. Returns the offset of a struct member with given name.
##### **pffi-struct-get** pffi-struct member-name -> object ##### **pffi-struct-get** pffi-struct member-name -> object
<a name="pffi-struct-get"></a>
Returns the value of the givens struct member. Returns the value of the givens struct member.
##### **pffi-struct-set!** pffi-struct member-name value ##### **pffi-struct-set!** pffi-struct member-name value
<a name="pffi-struct-set!"></a>
Sets the value of the givens struct member. It is up to you to make sure that the type of value is Sets the value of the givens struct member. It is up to you to make sure that the type of value is
correct. correct.
##### **pffi-define** scheme-name shared-object c-name return-type argument-types ##### **pffi-define** scheme-name shared-object c-name return-type argument-types
<a name="pffi-define"></a>
Defines a new foreign function to be used from Scheme code. For example: Defines a new foreign function to be used from Scheme code. For example:
@ -356,6 +415,7 @@ Defines a new foreign function to be used from Scheme code. For example:
(c-puts "Message brought to you by FFI!") (c-puts "Message brought to you by FFI!")
##### **pffi-define-callback** scheme-name return-type argument-types procedure ##### **pffi-define-callback** scheme-name return-type argument-types procedure
<a name="pffi-define-callback"></a>
Defines a new Sceme function to be used as callback to C code. For example: Defines a new Sceme function to be used as callback to C code. For example:
@ -395,3 +455,5 @@ Defines a new Sceme function to be used as callback to C code. For example:
(display array) (display array)
(newline) (newline)
;> (1 2 3) ;> (1 2 3)
</main>

980
documentation/R7RS-PFFI.html Normal file
View File

@ -0,0 +1,980 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="date" content=''>
<title>Portable Foreign Function Interface for R7RS
Documentation</title>
<style>
h5 { font-weight: normal; }
table { width: 250%; }
nav { float: left; width: 20%;}
main { float: right; width: 80%; }
pre { background-color: lightgrey; }
</style>
</head>
<body>
<h1 id="portable-foreign-function-interface-for-r7rs">Portable
Foreign Function Interface for R7RS</h1>
<p>Portable foreign function interface for R7RS. It is portable
in the sense that it supports multiple implementations, as
opposed to being portable by conforming to some
specification.</p>
<p><a
href="https://todo.sr.ht/~retropikzel/r7rs-pffi">Project</a></p>
<p><a href="https://sr.ht/~retropikzel/r7rs-pffi/trackers">Issue
trackers</a></p>
<p><a href="https://sr.ht/~retropikzel/r7rs-pffi/lists">Maling
lists</a></p>
<p><a
href="https://jenkins.scheme.org/job/r7rs_pffi/job/r7rs-pffi/">Jenkins</a></p>
<h2 id="table-of-contents">Table of contents</h2>
<nav>
<ul>
<li><a href="#goals">Goals</a></li>
<li><a href="#non-goals">Non Goals</a></li>
<li><a href="#status">Status</a>
<ul>
<li><a href="#current-caveats">Current caveats</a></li>
</ul></li>
<li><a href="#implementation-table">Implementation table</a>
<ul>
<li><a href="#beta">Beta</a></li>
<li><a href="#alpha">Alpha</a></li>
<li><a href="#not-started">Not started</a></li>
<li><a href="#other">Other</a></li>
</ul></li>
<li><a href="#documentation">Documentation</a>
<ul>
<li><a href="#usage">Usage</a>
<ul>
<li><a href="#usage-chibi">Chibi</a></li>
<li><a href="#usage-chicken">Chicken</a></li>
<li><a href="#usage-racket">Racket</a></li>
<li><a href="#usage-kawa">Kawa</a></li>
</ul></li>
<li><a href="#reference">Reference</a></li>
<li><a href="#types">Types</a></li>
<li><a href="#procedures-and-macros">Procedures and macros</a>
<ul>
<li><a href="#pffi-init">pffi-init</a></li>
<li><a href="#pffi-size-of">pffi-size-of</a></li>
<li><a href="#pffi-align-of">pffi-align-of</a></li>
<li><a
href="#pffi-shared-object-auto-load">pffi-shared-object-auto-load</a></li>
<li><a
href="#pffi-shared-object-load">pffi-shared-object-load</a></li>
<li><a href="#pffi-pointer-null">pffi-pointer-null</a></li>
<li><a href="#pffi-pointer-null?">pffi-pointer-null?</a></li>
<li><a
href="#pffi-pointer-allocate">pffi-pointer-allocate</a></li>
<li><a
href="#pffi-pointer-address">pffi-pointer-address</a></li>
<li><a href="#pffi-pointer?">pffi-pointer?</a></li>
<li><a href="#pffi-pointer-free">pffi-pointer-free</a></li>
<li><a href="#pffi-pointer-set!">pffi-pointer-set!</a></li>
<li><a href="#pffi-pointer-get">pffi-pointer-get</a></li>
<li><a
href="#pffi-string-to-pointer">pffi-string-&gt;pointer</a></li>
<li><a
href="#pffi-pointer-to-string">pffi-pointer-&gt;string</a></li>
<li><a href="#pffi-struct-make">pffi-struct-make</a></li>
<li><a href="#pffi-struct-pointer">pffi-struct-pointer</a></li>
<li><a
href="#pffi-struct-offset-get">pffi-struct-offset-get</a></li>
<li><a href="#pffi-struct-get">pffi-struct-get</a></li>
<li><a href="#pffi-struct-set!">pffi-struct-set!</a></li>
<li><a href="#pffi-define">pffi-define</a></li>
<li><a
href="#pffi-define-callback">pffi-define-callback</a></li>
</ul></li>
</ul></li>
</ul>
</nav>
<main>
<h2 id="goals">Goals</h2>
<p><a name="goals"></a></p>
<ul>
<li>Support only R7RS implementations</li>
<li>Same interface on all implementations
<ul>
<li>Some things that are procedures on one implementation are
macros on other, but they must behave the same</li>
</ul></li>
<li>Stability and being boring after 1.0.0 is reached</li>
</ul>
<h2 id="non-goals">Non goals</h2>
<p><a name="non-goals"></a></p>
<ul>
<li>To have every possible FFI feature</li>
<li>Compiling of used library C code at any point
<ul>
<li>That is no stubs, no C code generated by the library and so
on</li>
<li>The pffi library itself may require compilation on
installation</li>
</ul></li>
</ul>
<h2 id="status">Status</h2>
<p><a name="status"></a></p>
<p>Currently the interface of the library is in okay shape. It
propably will not change much but no guarantees are being made
just yet.</p>
<p>Due to supporting many different Scheme implementations,
different parts of this software are in different stage. As a
whole it is still in <strong>alpha</strong> stage. That said the
interface should not be changing anymore and some
implementations are in <strong>beta</strong>.</p>
<h3 id="current-caveats">Current caveats</h3>
<p><a name="current-caveats"></a></p>
<ul>
<li>No way to pass structs by value</li>
<li>Most implementations are missing callback support</li>
</ul>
<h2 id="implementation-table">Implementation table</h2>
<p><a name="implementation-table"></a></p>
<h3 id="beta">Beta</h3>
<p><a name="beta"></a></p>
<table>
<colgroup>
<col style="width: 3%" />
<col style="width: 2%" />
<col style="width: 3%" />
<col style="width: 7%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 3%" />
<col style="width: 5%" />
</colgroup>
<thead>
<tr class="header">
<th></th>
<th style="text-align: center;">pffi-init</th>
<th style="text-align: center;">pffi-size-of</th>
<th
style="text-align: center;">pffi-shared-object-auto-load</th>
<th style="text-align: center;">pffi-shared-object-load</th>
<th style="text-align: center;">pffi-pointer-null</th>
<th style="text-align: center;">pffi-pointer-null?</th>
<th style="text-align: center;">pffi-pointer-allocate</th>
<th style="text-align: center;">pffi-pointer-address</th>
<th style="text-align: center;">pffi-pointer?</th>
<th style="text-align: center;">pffi-pointer-free</th>
<th style="text-align: center;">pffi-pointer-set!</th>
<th style="text-align: center;">pffi-pointer-get</th>
<th style="text-align: center;">pffi-string-&gt;pointer</th>
<th style="text-align: center;">pffi-pointer-&gt;string</th>
<th style="text-align: center;">pffi-struct-make</th>
<th style="text-align: center;">pffi-struct-pointer</th>
<th style="text-align: center;">pffi-struct-offset-get</th>
<th style="text-align: center;">pffi-struct-get</th>
<th style="text-align: center;">pffi-struct-set!</th>
<th style="text-align: center;">pffi-define</th>
<th style="text-align: center;">pffi-define-callback</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Chibi</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Gauche</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>Guile</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="even">
<td>Kawa</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="odd">
<td>Racket</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="even">
<td>Saggittarius</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
</tbody>
</table>
<h3 id="alpha">Alpha</h3>
<p><a name="alpha"></a></p>
<table>
<colgroup>
<col style="width: 3%" />
<col style="width: 2%" />
<col style="width: 3%" />
<col style="width: 7%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 3%" />
<col style="width: 5%" />
</colgroup>
<thead>
<tr class="header">
<th></th>
<th style="text-align: center;">pffi-init</th>
<th style="text-align: center;">pffi-size-of</th>
<th
style="text-align: center;">pffi-shared-object-auto-load</th>
<th style="text-align: center;">pffi-shared-object-load</th>
<th style="text-align: center;">pffi-pointer-null</th>
<th style="text-align: center;">pffi-pointer-null?</th>
<th style="text-align: center;">pffi-pointer-allocate</th>
<th style="text-align: center;">pffi-pointer-address</th>
<th style="text-align: center;">pffi-pointer?</th>
<th style="text-align: center;">pffi-pointer-free</th>
<th style="text-align: center;">pffi-pointer-set!</th>
<th style="text-align: center;">pffi-pointer-get</th>
<th style="text-align: center;">pffi-string-&gt;pointer</th>
<th style="text-align: center;">pffi-pointer-&gt;string</th>
<th style="text-align: center;">pffi-struct-make</th>
<th style="text-align: center;">pffi-struct-pointer</th>
<th style="text-align: center;">pffi-struct-offset-get</th>
<th style="text-align: center;">pffi-struct-get</th>
<th style="text-align: center;">pffi-struct-set!</th>
<th style="text-align: center;">pffi-define</th>
<th style="text-align: center;">pffi-define-callback</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Chicken-5</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="even">
<td>Cyclone</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>Gambit</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Gerbil</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>Larceny</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Mosh</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="odd">
<td>Skint</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Stklos</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>tr7</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Ypsilon</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
</tbody>
</table>
<h3 id="not-started">Not started</h3>
<p><a name="not-started"></a></p>
<ul>
<li><a href="https://lips.js.org/">LIPS</a>
<ul>
<li>Will work on nodejs by using some C FFI library from
npm</li>
<li>Javascript side needs design</li>
</ul></li>
<li><a href="https://www.biwascheme.org/">Biwascheme</a>
<ul>
<li>Will work on nodejs by using some C FFI library from
npm</li>
<li>Javascript side needs design</li>
</ul></li>
<li><a
href="https://www.gnu.org/software/mit-scheme/">MIT-Scheme</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
<li><a
href="https://gitlab.com/mbabich/airship-scheme">Airship</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
<li><a href="https://gambitscheme.org/">Other gambit targets</a>
<ul>
<li>Gambit compiles to different targets other than C too, for
example Javascript. It would be cool and interesting to see if
this FFI could also support some of those</li>
<li>When LIPS and Biwascheme Javascript side is done then Gambit
should be done too</li>
</ul></li>
<li><a
href="https://codeberg.org/prescheme/s48-r7rs">s48-r7rs</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
<li><a
href="https://codeberg.org/prescheme/prescheme">prescheme</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
</ul>
<h3 id="other">Other</h3>
<p><a name="other"></a></p>
<ul>
<li><a
href="https://scheme.fail://ccrma.stanford.edu/software/snd/snd/s7.html">s7</a>
<ul>
<li>Propably does not need FFI as it is embeddable only</li>
</ul></li>
<li><a href="https://scheme.fail/">Loko</a>
<ul>
<li>Desires no C interop, I can respect that</li>
</ul></li>
</ul>
<h2 id="documentation">Documentation</h2>
<p><a name="documentation"></a></p>
<h3 id="usage">Usage</h3>
<p><a name="usage"></a></p>
<h4 id="chibi">Chibi</h4>
<p><a name="usage-chibi"></a></p>
<p>Needs libffi-dev, on Debina/Ubuntu/Mint install with:</p>
<pre><code>apt install libffi-dev</code></pre>
<p>Build with:</p>
<pre><code>chibi-ffi retropikzel/r7rs-pffi/r7rs-pffi-chibi.stub
gcc -o retropikzel/r7rs-pffi/r7rs-pffi-chibi.so -fPIC -shared retropikzel/r7rs-pffi/r7rs-pffi-chibi.c -lchibi-scheme -lffi</code></pre>
<h4 id="chicken">Chicken</h4>
<p><a name="usage-chicken"></a></p>
<p>Needs <a href="https://wiki.call-cc.org/eggref/5/r7rs">r7rs
egg</a>, install with:</p>
<pre><code>chicken-install r7rs</code></pre>
<h4 id="racket">Racket</h4>
<p><a name="usage-racket"></a></p>
<p>Needs <a
href="https://github.com/lexi-lambda/racket-r7rs">racket-r7rs</a>,
install with:</p>
<pre><code>raco pkg install --auto r7rs</code></pre>
<h4 id="kawa">Kawa</h4>
<p><a name="usage-kawa"></a></p>
<p>Kawa Needs at least Java version 22</p>
<p>Needs jvm flags:</p>
<ul>
<li>–add-exports
java.base/jdk.internal.foreign.abi=ALL-UNNAMED</li>
<li>–add-exports
java.base/jdk.internal.foreign.layout=ALL-UNNAMED</li>
<li>–add-exports java.base/jdk.internal.foreign=ALL-UNNAMED</li>
<li>–enable-native-access=ALL-UNNAMED</li>
</ul>
<h3 id="reference">Reference</h3>
<p><a name="reference"></a></p>
<h4 id="types">Types</h4>
<p><a name="types"></a></p>
<p>Types are given as symbols, for example ’int8 or
’pointer.</p>
<ul>
<li>int8</li>
<li>uint8</li>
<li>int16</li>
<li>uint16</li>
<li>int32</li>
<li>uint32</li>
<li>int64</li>
<li>uint64</li>
<li>char</li>
<li>unsigned-char</li>
<li>short</li>
<li>unsigned-short</li>
<li>int</li>
<li>unsigned-int</li>
<li>long</li>
<li>unsigned-long</li>
<li>float</li>
<li>double</li>
<li>pointer</li>
<li>callback
<ul>
<li>Callback function</li>
</ul></li>
</ul>
<h4 id="procedures-and-macros">Procedures and macros</h4>
<p><a name="procedures-and-macros"></a></p>
<p>Some of these are procedures and some macros, it might also
change implementation to implementation.</p>
<h5 id="pffi-init"><strong>pffi-init</strong></h5>
<p><a name="pffi-init"></a></p>
<p>Always call this first, on most implementation it does
nothing but some implementations might need initialisation
run.</p>
<h5
id="pffi-size-of-object---number"><strong>pffi-size-of</strong>
object -&gt; number</h5>
<p><a name="pffi-size-of"></a></p>
<p>Returns the size of the pffi-struct, pffi-enum or
pffi-type.</p>
<h5
id="pffi-align-of-type---number"><strong>pffi-align-of</strong>
type -&gt; number</h5>
<p><a name="pffi-align-of"></a></p>
<p>Returns the align of the type.</p>
<h5
id="pffi-shared-object-auto-load-headers-shared-object-name-options---object"><strong>pffi-shared-object-auto-load</strong>
headers shared-object-name [options] -&gt; object</h5>
<p><a name="pffi-shared-object-auto-load"></a></p>
<p>Load given shared object automatically searching many
predefined paths.</p>
<p>Takes as argument a list of C headers, these are for the
compiler ones. And an shared-object name, used by the dynamic
FFI’s. The name of the shared object should not contain suffix
like .so or .dll. Nor should it contain any prefix like
“lib”.</p>
<p>Additional options argument can be provided, theys should be
a pair with a keyword. The options are:</p>
<ul>
<li>additional-versions
<ul>
<li>Search for additional versions of shared object, given
shared object “c” and additional versions “6” “7” on linux the
files “libc”, “libc.6”, “libc.7” are searched for.</li>
<li>Can be either numbers or strings</li>
</ul></li>
<li>additional-paths
<ul>
<li>Give additional paths to search shared objects for</li>
</ul></li>
</ul>
<p>Example:</p>
<pre><code>(define libc-stdlib
(cond-expand
(windows (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) &quot;ucrtbase&quot;))
(else (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;)
&quot;c&quot;
&#39;(additional-versions . (&quot;6&quot;))
&#39;(additional-search-paths . (&quot;.&quot;))))))</code></pre>
<h5
id="pffi-shared-object-load-headers-path-options"><strong>pffi-shared-object-load</strong>
headers path [options]</h5>
<p><a name="pffi-shared-object-load"></a></p>
<p>It is recommended to use the pffi-shared-object-auto-load
instead of this directly.</p>
<p>Headers is a list of strings needed to be included, for
example</p>
<pre><code>(list &quot;curl/curl.h&quot;)</code></pre>
<p>Path is the full path of the shared object without any “lib”
prefix or “.so/.dll” suffix. For example:</p>
<pre><code>&quot;curl&quot;</code></pre>
<p>Options:</p>
<ul>
<li>additional-versions
<ul>
<li>List of different versions of library to try, for example
(list “.0” “.1”)</li>
</ul></li>
</ul>
<h5
id="pffi-pointer-null---pointer"><strong>pffi-pointer-null</strong>
-&gt; pointer</h5>
<p><a name="pffi-pointer-null"></a></p>
<p>Returns a new NULL pointer.</p>
<h5
id="pffi-pointer-null-pointer---boolean"><strong>pffi-pointer-null?</strong>
pointer -&gt; boolean</h5>
<p><a name="pffi-pointer-null?"></a></p>
<p>Returns #t if given pointer is null pointer, #f
otherwise.</p>
<h5
id="pffi-pointer-allocate-size---pointer"><strong>pffi-pointer-allocate</strong>
size -&gt; pointer</h5>
<p><a name="pffi-pointer-allocate"></a></p>
<p>Returns newly allocated pointer of given size.</p>
<h5
id="pffi-pointer-address-pointer---number"><strong>pffi-pointer-address</strong>
pointer -&gt; number</h5>
<p><a name="pffi-pointer-address"></a></p>
<p>Returns the address of given pointer as number.</p>
<h5
id="pffi-pointer-object---boolean"><strong>pffi-pointer?</strong>
object -&gt; boolean</h5>
<p><a name="pffi-pointer?"></a></p>
<p>Returns #t if given object is pointer, #f otherwise.</p>
<h5
id="pffi-pointer-free-pointer"><strong>pffi-pointer-free</strong>
pointer</h5>
<p><a name="pffi-pointer-free"></a></p>
<p>Frees given pointer.</p>
<h5
id="pffi-pointer-set-pointer-type-offset-value"><strong>pffi-pointer-set!</strong>
pointer type offset value</h5>
<p><a name="pffi-pointer-set!"></a></p>
<p>Sets the value on a pointer on given offset. For example:</p>
<pre><code>(define p (pffi-pointer-allocate 128))
(pffi-pointer-set! p &#39;int 64 100)</code></pre>
<p>Would set the offset of 64, on pointer p to value 100.</p>
<h5
id="pffi-pointer-get-pointer-type-offset---object"><strong>pffi-pointer-get</strong>
pointer type offset -&gt; object</h5>
<p><a name="pffi-pointer-get"></a></p>
<p>Gets the value from a pointer on given offset. For
example:</p>
<pre><code>(define p (pffi-pointer-allocate 128))
(pffi-pointer-set! p &#39;int 64 100)
(pffi-pointer-get p &#39;int 64)
&gt; 100</code></pre>
<h5
id="pffi-string-pointer-string---pointer"><strong>pffi-string-&gt;pointer</strong>
string -&gt; pointer</h5>
<p><a name="pffi-string-to-pointer"></a></p>
<p>Makes pointer out of a given string.</p>
<h5
id="pffi-pointer-string-pointer---string"><strong>pffi-pointer-&gt;string</strong>
pointer -&gt; string</h5>
<p><a name="pffi-pointer-to-string"></a></p>
<p>Makes string out of a given pointer.</p>
<h5
id="pffi-struct-make-c-type-members-.-pointer---pffi-struct"><strong>pffi-struct-make</strong>
c-type members . pointer -&gt; pffi-struct</h5>
<p><a name="pffi-struct-make"></a></p>
<p>Creates a new pffi-struct and allocates pointer for it. The
members argument is a list of member names and types. For
example:</p>
<pre><code>(define color (pffi-struct-make &#39;color &#39;((int8 . r) (int8 . g) (int8 . b) (int8 .a ))))
(define test (pffi-struct-make &quot;struct test&quot; &#39;((int8 . r) (int8 . g) (int8 . b) (int8 .a ))))</code></pre>
<p>C-type argument can be symbol or a string.</p>
<h5
id="pffi-struct-pointer-pffi-struct---pointer"><strong>pffi-struct-pointer</strong>
pffi-struct -&gt; pointer</h5>
<p><a name="pffi-struct-pointer"></a></p>
<p>Returns the pointer that holds the struct content. You need
to use this when passing a struct as a pointer to foreign
functions.</p>
<pre><code>(define s (pffi-struct-make &#39;test &#39;((int . r) (int . g) (int . b))))
(pffi-struct-pointer s)</code></pre>
<h5
id="pffi-struct-offset-get-member-name---number"><strong>pffi-struct-offset-get</strong>
member-name -&gt; number</h5>
<p><a name="pffi-struct-offset-get"></a></p>
<p>Returns the offset of a struct member with given name.</p>
<h5
id="pffi-struct-get-pffi-struct-member-name---object"><strong>pffi-struct-get</strong>
pffi-struct member-name -&gt; object</h5>
<p><a name="pffi-struct-get"></a></p>
<p>Returns the value of the givens struct member.</p>
<h5
id="pffi-struct-set-pffi-struct-member-name-value"><strong>pffi-struct-set!</strong>
pffi-struct member-name value</h5>
<p><a name="pffi-struct-set!"></a></p>
<p>Sets the value of the givens struct member. It is up to you
to make sure that the type of value is correct.</p>
<h5
id="pffi-define-scheme-name-shared-object-c-name-return-type-argument-types"><strong>pffi-define</strong>
scheme-name shared-object c-name return-type argument-types</h5>
<p><a name="pffi-define"></a></p>
<p>Defines a new foreign function to be used from Scheme code.
For example:</p>
<pre><code>(define libc-stdlib
(cond-expand
(windows (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;ucrtbase&quot; (list &quot;&quot;)))
(else (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;c&quot; (list &quot;&quot; &quot;6&quot;)))))
(pffi-define c-puts libc-stdlib &#39;puts &#39;int (list &#39;pointer))
(c-puts &quot;Message brought to you by FFI!&quot;)</code></pre>
<h5
id="pffi-define-callback-scheme-name-return-type-argument-types-procedure"><strong>pffi-define-callback</strong>
scheme-name return-type argument-types procedure</h5>
<p><a name="pffi-define-callback"></a></p>
<p>Defines a new Sceme function to be used as callback to C
code. For example:</p>
<pre><code>; Load the shared library
(define libc-stdlib
(cond-expand
(windows (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;ucrtbase&quot; (list &quot;&quot;)))
(else (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;c&quot; (list &quot;&quot; &quot;6&quot;)))))
; Define C function that takes a callback
(pffi-define qsort libc-stdlib &#39;qsort &#39;void (list &#39;pointer &#39;int &#39;int &#39;callback))
; Define our callback
(pffi-define-callback compare
&#39;int
(list &#39;pointer &#39;pointer)
(lambda (pointer-a pointer-b)
(let ((a (pffi-pointer-get pointer-a &#39;int 0))
(b (pffi-pointer-get pointer-b &#39;int 0)))
(cond ((&gt; a b) 1)
((= a b) 0)
((&lt; a b) -1)))))
; Create new array of ints to be sorted
(define array (pffi-pointer-allocate (* (pffi-size-of &#39;int) 3)))
(pffi-pointer-set! array &#39;int (* (pffi-size-of &#39;int) 0) 3)
(pffi-pointer-set! array &#39;int (* (pffi-size-of &#39;int) 1) 2)
(pffi-pointer-set! array &#39;int (* (pffi-size-of &#39;int) 2) 1)
(display array)
(newline)
;&gt; (3 2 1)
; Sort the array
(qsort array 3 (pffi-size-of &#39;int) compare)
(display array)
(newline)
;&gt; (1 2 3)</code></pre>
</main>
</body>
</html>

BIN
documentation/R7RS-PFFI.pdf Normal file
View File

Binary file not shown.

2
templates/css/pdf-documentation.css Normal file
View File

@ -0,0 +1,2 @@
h5 { font-weight: normal; }
pre { background-color: lightgrey; }

18
templates/documentation.html Normal file
View File

@ -0,0 +1,18 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="date" content='$date-meta$'>
<title>$title$</title>
<style>
h5 { font-weight: normal; }
table { width: 250%; }
nav { float: left; width: 20%;}
main { float: right; width: 80%; }
pre { background-color: lightgrey; }
</style>
</head>
<body>
$body$
</body>
</html>